search

nbanb / fbx-delta-nba_bash_api.sh

Access FreeboxOS API from bash
Other
3 stars 1 forks source link
api bash delta dhcp download freebox freebox-delta freebox-download freebox-server iliadbox library network vm websocat

readme

fbx-delta-nba_bash_api.sh


Access FreeboxOS API from BASH


Supported Freebox Supported Iliadbox Virtual Machine Support
ULTRA - YES
DELTA - YES
POP POP NO
REVOLUTION - NO
ONE - NO




Table of Contents:

1. Direct access to major part of this README:

Type Description Link
howto example Quick HOWTO example of how to use this lib QUICK START FULL EXAMPLE
API FreeboxOS API considerations API
core Create application & login API LOGIN FUNCTIONS
core Functions for calling API in all cases CALL FUNCTIONS
core Functions for retrieving Freebox component status STATUS FUNCTIONS
core Functions for checking validity or success CHECK FUNCTIONS
frontend Functions for managing downloads DOWNLOAD FUNCTIONS
frontend example Example of usage of downloads function DOWNLOAD EXAMPLE
frontend Functions for managing downloads share links SHARE LINK FUNCTIONS
frontend network Functions for managing DHCP reservations NETWORK DHCP FUNCTIONS
frontend network Functions for managing incomming NAT redirections NETWORK NAT FUNCTIONS
API Filesystem API considerations FILESYSTEM
frontend Functions for managing filesystem tasks FILESYSTEM TASK FUNCTIONS
frontend Functions for managing filesystem operations FILESYSTEM OPERATION FUNCTIONS
frontend VM Functions for managing VM VIRTUAL MACHINES FUNCTIONS
frontend Functions for formatting API reply of frontend functions API REPLY OUTPUT
core Functions for making direct actions on box from API API ACTIONS


2. Extras actions / configurations needed on your box when using API:

Type Description Link
howto Configure your applications access right in your box OS GRANT API ACCESS
info Get a public URL URL
info Get a TLS certificate TLS CERTIFICATES
howto Configure remote access to your box REMOTE ACCESS
howto Configure public URL and TLS certificate on your box CONFIGURE URL AND TLS
howto Ask ISP for a 'full-stack' IPv4 address FULL-STACK IPV4


3. External ressources:

Type Description Link
API SDK Freebox API SDK FreeboxOS API SDK
API list Freebox API list All FreeboxOS API
tool Freebox Delta Virtual Machines management (complete bash tool) fbxvm-ctrl


TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

Quick Start

You need to have curl and openssl installed.

If you want to use your own URL (WAN or LAN), configure 'FREEBOX_xxx_URL=' and 'FREEBOX_xxx_CACERT=' If you are in Italy, configure 'ILIADBOX_xxx_URL=' and 'ILIADBOX_xxx_CACERT=' instead

For the WAN URL, if your box is not reachable on HTTPS port 443, please add ':#PORT' to the WAN URL as it's done in the following example :

FREEBOX_WAN_URL="https://fbx.my-public-domain.net:4011"
FREEBOX_WAN_CACERT="/path/to/my/own/pki/ROOT/CA/CERTIFICATE"

To connect your freebox API, you must create and grant access to an application in your freebox Use function 'authorize_application' to create an application token and grant access on the freebox LCD

$ source ./fbx-delta-nba_bash_api.sh
$ authorize_application  'MyWonderfull.app'  'My Wonderfull App'  '1.0.0'  'GNU Linux'

Login with your APP_ID and APP_TOKEN 

$ login_freebox "$MY_APP_ID" "$MY_APP_TOKEN"
$ answer=$(call_freebox_api /system)
$ get_json_value_for_key "$answer" result.model_info.net_operator
free_fra
TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

Quick Start FULL Example

Get the library

$ curl -L https://github.com/nbanb/fbx-delta-nba_bash_api.sh/raw/nbanb-freebox-api/fbx-delta-nba_bash_api.sh > fbx-delta-nba_bash_api.sh

Configure the library 

$ sed -i 's/^_APP_PASSWORD=""/_APP_PASSWORD="MySTRONGpassword"/' ./fbx-delta-nba_bash_api.sh 
$
$ # Next lines are optional, except if you want to access Freebox API over internet
$ sed -i 's|^FREEBOX_WAN_URL=""|FREEBOX_WAN_URL="https://fbx.my-public-domain.net:4011"|' ./fbx-delta-nba_bash_api.sh
$ sed -i 's|^FREEBOX_WAN_CACERT=""|FREEBOX_WAN_CACERT="/path/to/my/own/pki/ROOT/CA/CERTIFICATE"|' ./fbx-delta-nba_bash_api.sh

Create an application token which can access Freebox API

$ source ./fbx-delta-nba_bash_api.sh
$ authorize_application  'MyWonderfull.app'  'My Wonderfull App'  '1.0.0'  'GNU Linux'
Please grant/deny access to the application on the Freebox LCD...
Authorization granted

APP_ID="MyWonderfull.app"
APP_TOKEN="4uZTLMMwSyiPB42tSCWLpSSZbXIYi+d+F32tVMx2j1p8oSUUk4Awr/OMZne4RRlY"
For detailed procedure to get an APP_TOKEN see: LOGIN

Now you can create an application 

$ cat my-box-uptime.sh
#!/bin/bash

MY_APP_ID="MyWonderfull.app"
MY_APP_TOKEN="4uZTLMMwSyiPB42tSCWLpSSZbXIYi+d+F32tVMx2j1p8oSUUk4Awr/OMZne4RRlY"

# source the fbx-delta-nba_bash_api.sh
source ./fbx-delta-nba_bash_api.sh

# login
login_freebox "$MY_APP_ID" "$MY_APP_TOKEN"

# get system data
answer=$(call_freebox_api /system/)

# extract your box uptime 
uptime=$(get_json_value_for_key "${answer}" 'result.uptime')

# print the result
echo "My box is up since $uptime"

Or you can use the library's functions directly from your bash terminal Create your 'logintomybox' file to source:

$ # configure 'logintomybox' with your APP_ID and APP_TOKEN
$  
$ echo "#!/bin/bash" >logintomybox
$ echo "source ./fbx-delta-nba_bash_api.sh" >>logintomybox
$ echo 'MY_APP_ID="PutHereYourAPP_ID"' >>logintomybox
$ echo 'MY_APP_TOKEN="PutHereYourAPP_TOKEN"' >>logintomybox
$ echo 'login_freebox "$MY_APP_ID" "$MY_APP_TOKEN"' >>logintomybox

Now, you can source your 'logintomyfbx' file to access library function directly in your bash command shell: 

$ source logintomybox
$  
$ # now you can use the library functions directly in your terminal: 
$ # ex: reboot your box (your app need to be granted to modify your box settings)
$ reboot_freebox
{"success":true}
If you get an error saying that your application is not granted to use this API, see: GRANT API ACCESS
TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API

NOTE
TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

LOGIN FUNCTIONS

Obtain an application token / login / logout the API

authorize_application app_id app_name app_version device_name*

It is used to obtain a token to identify a new application (need to be done only once)

Example
$ source ./fbx-delta-nba_bash_api.sh
$ authorize_application 'MyFbxVMapp' 'fbx VM control' '1.0.0-a' 'FreeboxVM-Linux'
Please grant/deny access to the app on the Freebox LCD...
Authorization granted

MY_APP_ID="MyFbxVMapp"
MY_APP_TOKEN="I7Sj+jpquj0rnPVSjLokXhy3gglOZflOQDTxjA8Vxdbma/VtoRwhR/nIluBuG8Wt"
Process

First run: 

source ./fbx-delta-nba_bash_api.sh
authorize_application 'MyFbxVMapp' 'fbx VM control' '1.0.0-a' 'FreeboxVM-Linux'
Please grant/deny access to the application on the Freebox LCD...
Picture

fbxapp-w

Now grant access on Feeebox LCD :

fbx-vapp

fbx-val0

fbx-val-ok

And now on your bash terminal, you will see your APP_ID and APP_TOKEN printed : 

$ authorize_application 'MyFbxVMapp' 'fbx VM control' '1.0.0-a' 'FreeboxVM-Linux'
Please grant/deny access to the application on the Freebox LCD...
Authorization granted

MY_APP_ID="MyFbxVMapp"
MY_APP_TOKEN="I7Sj+jpquj0rnPVSjLokXhy3gglOZflOQDTxjA8Vxdbma/VtoRwhR/nIluBuG8Wt"
Picture:

fbxapp-ok

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

login_freebox app_id app_token*

It is used to log in the application to the freebox API (you need the application token obtain from authorize_application function). WARNING : The original function had been modified and renamed to login_fbx as it's now used as an underlying function called by login_freebox which login and also publish to subshell 2 variables (_APP_ID and _APP_ENCRYPTED_TOKEN). Those 2 variables are used by the library to auto re-login when the session had timeout but you're watching for a task that is longer than the session timeout.

Example
#!/bin/bash

MY_APP_ID="MyWonderfull.app"
MY_APP_TOKEN="4uZTLMMwSyiPB42tSCWLpSSZbXIYi+d+F32tVMx2j1p8oSUUk4Awr/OMZne4RRlY"

# source the fbx-delta-nba_bash_api.sh
source ./fbx-delta-nba_bash_api.sh

# login
login_freebox "$MY_APP_ID" "$MY_APP_TOKEN"

* logout_freebox

It is used to logout the session opened by the application Return 0 if success, 1 otherwise

Example
logout_freebox

* check_login_freebox

It is used to check the status of the login session opened by the application Return 0 if success, 1 otherwise

Example
check_login_freebox

* app_login_freebox

After a first sucessfull login using function 'login_freebox', this function is able to retrieve credential from environnment variables (_APP_ID and _APP_ENCRYPTED_TOKEN) and to perform a login from the application or the library itself Return 0 if success, 1 otherwise

Example
app_login_freebox

* relogin_freebox

After a first sucessfull login using function 'login_freebox', this function is able to check the connection status and if the session is closed this function will re-login automatically from the application or from the library itself Return 0 if success, 1 otherwise

Example
relogin_freebox
TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API CALL FUNCTIONS

call_freebox_api api_path {optionnal_json_object}*

It is used to call a freebox API. This function make an HTTP GET request if no parameters are specified, and make an HTTP POST request if you provide '{optionnal_json_object}' parameter. The function will return a json string with an exit code of 0 if successfull. Otherwise it will return an empty string with an exit code of 1 and the reason of the error output to STDERR. You can find the list of all available api here or a more up-to-date developer documentation including specificities of your box directly in FreeboxOS here

Example
answer=$(call_freebox_api '/connection/xdsl')

add_freebox_api api_path {json_object}*

It is used to call a freebox API with a define HTTP POST request forcing "Content-Type: application/json" header. The function will return a json string with an exit code of 0 if successfull. Otherwise it will return an empty string with an exit code of 1 and the reason of the error output to STDERR. You can find the list of all available api here or a more up-to-date developer documentation including specificities of your box directly in FreeboxOS here

Example
answer=$(add_freebox_api '/vm/create' '{create_vm_json_object}')

get_freebox_api api_path URLoptions*

It is used to call a freebox API with a define HTTP GET request forcing parameter encoding in "with data-www-urlencode" format. The function will return a json string with an exit code of 0 if successfull. Otherwise it will return an empty string with an exit code of 1 and the reason of the error output to STDERR. You can find the list of all available api here or a more up-to-date developer documentation including specificities of your box directly in FreeboxOS here

Example
answer=$(get_freebox_api "/fs/ls/${base64_file_path}" "{fs_opts[@]}" 2>&1)

update_freebox_api api_path {json_object}*

It is used to call a freebox API with a define HTTP PUT request forcing "Content-Type: application/json" header. The function will return a json string with an exit code of 0 if successfull. Otherwise it will return an empty string with an exit code of 1 and the reason of the error output to STDERR. You can find the list of all available api here or a more up-to-date developer documentation including specificities of your box directly in FreeboxOS here

Example
answer=$(update_freebox_api '/vm/8' '{update_vm_json_object}')

del_freebox_api api_path*

It is used to call a freebox API with a define HTTP DELETE request. The function will return a json string with an exit code of 0 if successfull. Otherwise it will return an empty string with an exit code of 1 and the reason of the error output to STDERR. You can find the list of all available api here or a more up-to-date developer documentation including specificities of your box directly in FreeboxOS here

Example
answer=$(del_freebox_api '/vm/8')

call_freebox-ws_api api_path*

It is used to call a freebox Websocket API with websocket request. It need you install 'websocat' from here The function will return a websocket interractive connection and exit with an exit code of 0 if successfull. Otherwise it will return an empty string with an exit code of 1 and the reason of the error output to STDERR. You can find the list of all available websocket api directly in FreeboxOS here

Example
answer=$(call_freebox-ws_api '/vm/8/console')

get_json_value_for_key json_string key*

This function will return the value for the key from the json_string

Example
value=$(get_json_value_for_key "$answer" 'result.down.maxrate')

dump_json_keys_values json_string*

This function will dump on stdout all the keys values pairs from the json_string

Example
answer=$(call_freebox_api '/connection/')
dump_json_keys_values "$answer"
echo
bytes_down=$(get_json_value_for_key "$answer" 'result.bytes_down')
echo "bytes_down: $bytes_down"
success = true
result.type = rfc2684
result.rate_down = 40
result.bytes_up = 945912
result.rate_up = 0
result.bandwidth_up = 412981
result.ipv6 = 2a01:e35:XXXX:XXX::1
result.bandwidth_down = 3218716
result.media = xdsl
result.state = up
result.bytes_down = 2726853
result.ipv4 = XX.XXX.XXX.XXX
result = {"type":rfc2684,"rate_down":40,"bytes_up":945912,"rate_up":0,"bandwidth_up":412981,"ipv6":2a01:e35:XXXX:XXXX::1,"bandwidth_down":3218716,"media":xdsl,"state":up,"bytes_down":2726853,"ipv4":XX.XXX.XXX.XXX}

bytes_down: 2726853

* _check_success

This function will check if last command/function result is successfull. It is not a "system logical test"but a check on the answer returned by the API. It check that "success" has for value 'true' in API reply: {"success":true,"result":{...}} Return 0 if success, 1 otherwise

Example
$ answer=$(call_freebox_api downloads/add '{}')
Erreur lors de l'ajout du téléchargement: invalid_request
$ _check_success ${answer}
$ echo $?
1
TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API STATUS FUNCTIONS

* status_freebox

This function will return a json containing your freebox global status/infos (CPU, TEMP, FAN, DISK, etc). To be parsed by the script calling this function. Return code will be 0 if the freebox is alive and send its status, 1 otherwise.

Example
status_freebox

Result : 

{"success":true,"result":{"mac":"34:27:92:xx:xx:xx","sensors":[{"id":"temp_hdd1","name":"Disque dur 2","value":39},{"id":"temp_hdd3","name":"Disque dur 4","value":40},{"id":"temp_hdd2","name":"Disque dur 3","value":45},{"id":"temp_hdd0","name":"Disque dur 1","value":47},{"id":"temp_t2","name":"Température 2","value":51},{"id":"temp_t1","name":"Température 1","value":47},{"id":"temp_t3","name":"Température 3","value":47},{"id":"temp_cpu_cp_slave","name":"Température CPU CP Slave","value":80},{"id":"temp_cpu_ap","name":"Température CPU AP","value":71},{"id":"temp_cpu_cp_master","name":"Température CPU CP Master","value":80}],"model_info":{"customer_hdd_slots":4,"net_operator":"free_fra","supported_languages":["fra"],"has_dsl":true,"has_dect":true,"wifi_country":"FR","has_home_automation":true,"wifi_type":"2d4_5g_5g","pretty_name":"Freebox v7 (r1)","has_lan_sfp":true,"name":"fbxgw7-r1\/full","has_separate_internal_storage":true,"internal_hdd_size":0,"default_language":"fra","has_vm":true,"has_expansions":true},"fans":[{"id":"fan1_speed","name":"Ventilateur 2","value":2401},{"id":"fan0_speed","name":"Ventilateur 1","value":4208}],"expansions":[{"type":"security","present":true,"slot":1,"probe_done":true,"supported":true,"bundle":"985700J12345678"},{"type":"ftth_pon","present":true,"slot":2,"probe_done":true,"supported":true,"bundle":"955800A12345678"}],"board_name":"fbxgw7r","disk_status":"active","uptime":"8 jours 14 heures 53 minutes 21 secondes","uptime_val":744801,"user_main_storage":"FBX-500G","box_authenticated":true,"serial":"957602K123456789","firmware_version":"4.5.7"}}

* full_vm_detail

This function will print all json_vm_objects defined in the freebox

Example
full_vm_detail

Result :

{"success":true,"result":[{"mac":"ce:3e:20:b9:66:fc","cloudinit_userdata":"","cd_path":"","id":0,"os":"unknown","enable_cloudinit":false,"disk_path":"freebox-disk-path-wLnFjb3cy","vcpus":1,"memory":2048,"name":"14RV-FSRV-00","cloudinit_hostname":"","status":"stopped","bind_usb_ports":"","enable_screen":false,"disk_type":"qcow2"},{"mac":"3e:6e:bd:2b:fe:c7","cloudinit_userdata":"","cd_path":"","id":1,"os":"unknown","enable_cloudinit":false,"disk_path":"freebox-disk-path-zLnFjb3cy","vcpus":1,"memory":2048,"name":"14RV-FSRV-03","cloudinit_hostname":"","status":"stopped","bind_usb_ports":"","enable_screen":false,"disk_type":"qcow2"},{"mac":"ae:2c:8c:f6:3e:fb","cloudinit_userdata":"","cd_path":"","id":2,"os":"unknown","enable_cloudinit":false,"disk_path":"freebox-disk-path-xLnFjb3cy","vcpus":1,"memory":2048,"name":"14RV-FSRV-01","cloudinit_hostname":"","status":"running","bind_usb_ports":"","enable_screen":false,"disk_type":"qcow2"},{"mac":"5a:e3:85:db:26:ee","cloudinit_userdata":"","cd_path":"","id":3,"os":"unknown","enable_cloudinit":false,"disk_path":"freebox-disk-path-yLnFjb3cy","vcpus":1,"memory":4096,"name":"14RV-FSRV-02","cloudinit_hostname":"","status":"running","bind_usb_ports":"","enable_screen":false,"disk_type":"qcow2"},{"mac":"5e:e3:3a:13:ab:20","cloudinit_userdata":"","cd_path":"","id":4,"os":"unknown","enable_cloudinit":false,"disk_path":"freebox-disk-path-0LnFjb3cy","vcpus":1,"memory":2048,"name":"14RV-FSRV-04","cloudinit_hostname":"","status":"stopped","bind_usb_ports":"","enable_screen":false,"disk_type":"qcow2"},{"mac":"be:dd:fc:cc:53:8d","cloudinit_userdata":"","cd_path":"","id":5,"os":"unknown","enable_cloudinit":false,"disk_path":"freebox-disk-path-1LnFjb3cy","vcpus":1,"memory":2048,"name":"14RV-FSRV-05","cloudinit_hostname":"","status":"stopped","bind_usb_ports":"","enable_screen":false,"disk_type":"qcow2"},{"mac":"ba:81:13:4f:2f:4e","cloudinit_userdata":"","cd_path":"","id":6,"os":"unknown","enable_cloudinit":false,"disk_path":"freebox-disk-path-2LnFjb3cy","vcpus":1,"memory":2048,"name":"14RV-FSRV-06","cloudinit_hostname":"","status":"stopped","bind_usb_ports":"","enable_screen":false,"disk_type":"qcow2"},{"mac":"da:05:e4:43:33:5d","cloudinit_userdata":"","cd_path":"","id":7,"os":"unknown","enable_cloudinit":false,"disk_path":"freebox-disk-path-3LnFjb3cy","vcpus":1,"memory":2048,"name":"14RV-FSRV-07","cloudinit_hostname":"","status":"stopped","bind_usb_ports":"","enable_screen":false,"disk_type":"qcow2"},{"mac":"ce:3c:ee:b4:f4:f0","cloudinit_userdata":"ssh_authorized_keys:\n- ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAGEA3FSyQwBI6Z+nCSjUUk8EEAnnkhXlukKoUPND\/RRClWz2s5TCzIkd3Ou5+Cyz71X0XmazM3l5WgeErvtIwQMyT1KjNoMhoJMrJnWqQPOt5Q8zWd9qG7PBl9+eiH5qV7NZ mykey@host\n- ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA3I7VUf2l5gSn5uavROsc5HRDpZdQueUq5ozemNSj8T7enqKHOEaFoU2VoPgGEWC9RyzSQVeyD6s7APMcE82EtmW4skVEgEGSbDc1pvxzxtchBj78hJP6Cf5TCMFSXw+Fz5rF1dR23QDbN1mkHs7adr8GW4kSWqU7Q7NDwfIrJJtO7Hi42GyXtvEONHbiRPOe8stqUly7MvUoN+5kfjBM8Qqpfl2+FNhTYWpMfYdPUnE7u536WqzFmsaqJctz3gBxH9Ex7dFtrxR4qiqEr9Qtlu3xGn7Bw07\/+i1D+ey3ONkZLN+LQ714cgj8fRS4Hj29SCmXp5Kt5\/82cD\/VN3NtHw== smoser@brickies\n8ssh_keys:\nrsa_private: |\n -----BEGIN RSA PRIVATE KEY-----\n MIIBxwIBAAJhAKD0YSHy73nUgysO13XsJmd4fHiFyQ+00R7VVu2iV9Qcon2LZS\/x\n 1cydPZ4pQpfjEha6WxZ6o8ci\/Ea\/w0n+0HGPwaxlEG2Z9inNtj3pgFrYcRztfECb\n 1j6HCibZbAzYtwIBIwJgO8h72WjcmvcpZ8OvHSvTwAguO2TkR6mPgHsgSaKy6GJo\n PUJnaZRWuba\/HX0KGyhz19nPzLpzG5f0fYahlMJAyc13FV7K6kMBPXTRR6FxgHEg\n L0MPC7cdqAwOVNcPY6A7AjEA1bNaIjOzFN2sfZX0j7OMhQuc4zP7r80zaGc5oy6W\n p58hRAncFKEvnEq2CeL3vtuZAjEAwNBHpbNsBYTRPCHM7rZuG\/iBtwp8Rxhc9I5w\n ixvzMgi+HpGLWzUIBS+P\/XhekIjPAjA285rVmEP+DR255Ls65QbgYhJmTzIXQ2T9\n luLvcmFBC6l35Uc4gTgg4ALsmXLn71MCMGMpSWspEvuGInayTCL+vEjmNBT+FAdO\n W7D4zCpI43jRS9U06JVOeSc9CDk2lwiA3wIwCTB\/6uc8Cq85D9YqpM10FuHjKpnP\n REPPOyrAspdeOAV+6VKRavstea7+2DZmSUgE\n -----END RSA PRIVATE KEY-----\n\nrsa_public: ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAGEAoPRhIfLvedSDKw7XdewmZ3h8eIXJD7TRHtVW7aJX1ByifYtlL\/HVzJ09nilCl+MSFrpbFnqjxyL8Rr\/DSf7QcY\/BrGUQbZn2Kc22PemAWthxHO18QJvWPocKJtlsDNi3 smoser@localhost\n\ndsa_private: |\n -----BEGIN DSA PRIVATE KEY-----\n MIIBuwIBAAKBgQDP2HLu7pTExL89USyM0264RCyWX\/CMLmukxX0Jdbm29ax8FBJT\n pLrO8TIXVY5rPAJm1dTHnpuyJhOvU9G7M8tPUABtzSJh4GVSHlwaCfycwcpLv9TX\n DgWIpSj+6EiHCyaRlB1\/CBp9RiaB+10QcFbm+lapuET+\/Au6vSDp9IRtlQIVAIMR\n 8KucvUYbOEI+yv+5LW9u3z\/BAoGBAI0q6JP+JvJmwZFaeCMMVxXUbqiSko\/P1lsa\n LNNBHZ5\/8MOUIm8rB2FC6ziidfueJpqTMqeQmSAlEBCwnwreUnGfRrKoJpyPNENY\n d15MG6N5J+z81sEcHFeprryZ+D3Ge9VjPq3Tf3NhKKwCDQ0240aPezbnjPeFm4mH\n bYxxcZ9GAoGAXmLIFSQgiAPu459rCKxT46tHJtM0QfnNiEnQLbFluefZ\/yiI4DI3\n 8UzTCOXLhUA7ybmZha+D\/csj15Y9\/BNFuO7unzVhikCQV9DTeXX46pG4s1o23JKC\n \/QaYWNMZ7kTRv+wWow9MhGiVdML4ZN4XnifuO5krqAybngIy66PMEoQCFEIsKKWv\n 99iziAH0KBMVbxy03Trz\n -----END DSA PRIVATE KEY-----\n\ndsa_public: ssh-dss AAAAB3NzaC1kc3MAAACBAM\/Ycu7ulMTEvz1RLIzTbrhELJZf8Iwua6TFfQl1ubb1rHwUElOkus7xMhdVjms8AmbV1Meem7ImE69T0bszy09QAG3NImHgZVIeXBoJ\/JzByku\/1NcOBYilKP7oSIcLJpGUHX8IGn1GJoH7XRBwVub6Vqm4RP78C7q9IOn0hG2VAAAAFQCDEfCrnL1GGzhCPsr\/uS1vbt8\/wQAAAIEAjSrok\/4m8mbBkVp4IwxXFdRuqJKSj8\/WWxos00Ednn\/ww5QibysHYULrOKJ1+54mmpMyp5CZICUQELCfCt5ScZ9GsqgmnI80Q1h3Xkwbo3kn7PzWwRwcV6muvJn4PcZ71WM+rdN\/c2EorAINDTbjRo97NueM94WbiYdtjHFxn0YAAACAXmLIFSQgiAPu459rCKxT46tHJtM0QfnNiEnQLbFluefZ\/yiI4DI38UzTCOXLhUA7ybmZha+D\/csj15Y9\/BNFuO7unzVhikCQV9DTeXX46pG4s1o23JKC\/QaYWNMZ7kTRv+wWow9MhGiVdML4ZN4XnifuO5krqAybngIy66PMEoQ= smoser@localhost\n\nno_ssh_fingerprints: false\nssh:\nemit_keys_to_console: false","cd_path":"L0ZCWDI0VC9pc28vZGViaWFuLTExLjAuMC1hcm02NC1EVkQtMS5pc28=","id":8,"os":"debian","enable_cloudinit":true,"disk_path":"freebox-disk-path-4LnFjb3cy","vcpus":1,"memory":2048,"name":"14RV-FSRV-08","cloudinit_hostname":"14RV-FSRV-2048","status":"stopped","bind_usb_ports":["usb-external-type-c","usb-external-type-a"],"enable_screen":true,"disk_type":"qcow2"}]}

* vm_resource

This function will print a json containing availiable ressources for VM on freebox chassis

Example
vm_resource

Result :

{"success":true,"result":{"usb_used":false,"sata_used":false,"sata_ports":["sata-internal-p0","sata-internal-p1","sata-internal-p2","sata-internal-p3"],"used_memory":8192,"usb_ports":["usb-external-type-a","usb-external-type-c"],"used_cpus":3,"total_memory":15360,"total_cpus":3}}
TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API CHECK FUNCTIONS

check_tool program_name*

This function will check for external tool needed when running this program. Return code will be 0 if tool is installed and exit with a return code of 31 otherwise.

Example
check_tool websocat

websocat could not be found. Please install websocat

websocat install on amd64/emt64    
$ curl -L https://github.com/vi/websocat/releases/download/v1.11.0/websocat.x86_64-unknown-linux-musl >websocat-1.11_x86_64
$ sudo cp websocat-1.11_x86_64 /usr/bin/websocat-1.11_x86_64
$ sudo ln -s /usr/bin/websocat-1.11_x86_64 /usr/bin/websocat
$ sudo chmod +x /usr/bin/websocat-1.11_x86_64

websocat install on arm64: aarch64
$ curl -L https://github.com/vi/websocat/releases/download/v1.11.0/websocat.aarch64-unknown-linux-musl >websocat-1.11_aarch64 
$ sudo cp websocat-1.11_aarch64 /usr/bin/websocat-1.11_aarch64
$ sudo ln -s /usr/bin/websocat-1.11_aarch64 /usr/bin/websocat
$ sudo chmod +x /usr/bin/websocat-1.11_aarch64

check_tool_exit program_name*

This function is used inernally and is called by check_tool() function as it's underlying check process. Return code will be 0 if check is successfull, and exit with a return code of 1 otherwise. NOTE: you should not use this function directly

Example
check_tool_exit websocat

check_if_ip string*

This function will check if the provided argument is an IP address. Return code will be 0 if the provided argument is an IP address, and will exit with a return code of 1 if argument is not a valid IP address.

Example
check_if_ip 123.123.123
echo $?

check_if_rfc1918 string*

This function will check if the provided argument is an IP address defines in RFC1918. Return code will be 0 if the provided argument is an IP address defined in RFC1918, and will exit with a return code of 1 if argument is not a valid RFC1918 IP address.

Example
check_if_rfc1918 10.10.10.10
echo $?

check_if_port string*

This function will check if the provided argument is a valid port in range [1-65535]. Return code will be 0 if the provided argument is a valid port, and will exit with a return code of 1 if argument is not a valid port.

Example
check_if_port 4011
echo $?

check_if_mac string*

This function will check if the provided argument is a MAC address (only REGEX check on syntaxe, no call to the 'OUI' database). Return code will be 0 if the provided argument is a MAC address, and will exit with a return code of 1 if argument is not a valid MAC address.

Example
check_if_mac 00:a3:b6:c9:da:fb
echo $?
TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API FRONTEND - MINDSET

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API FRONTEND FUNCTIONS - DOWNLOAD

This API let you create download tasks, modify download tasks, monitor download tasks, list downloads tasks or show a particula tasks and finaly delete download tasks You can also retrieve download tasks logs.

check_and_feed_dl_param array_of_strings*

This function will check if the provided arguments are valid parameters for the function which is calling it depending of the "action" set by the calling function. If not, function param_dl_err will be called to set error and display help for the command depending on "action" set by the calling function. "action" are: 'add, enc, upd, show, del, mon, adv, log'. This function return a 'json' object or an 'as it must be formated object for the command' to be passed to "API CALL" functions

Example
action=enc
check_and_feed_dl_param download_url="https://images.jeedom.com/freebox/freeboxDelta.qcow2" hash="https://images.jeedom.com/freebox/SHA256SUMS" download_dir="/FBX24T/dl/vmimage/" filename="MyJedomDelta-efi-aarch64-nba0.qcow2"
echo -e  "${dl_enc_param_object}"
 download_url=https://images.jeedom.com/freebox/freeboxDelta.qcow2 hash=https://images.jeedom.com/freebox/SHA256SUMS download_dir=L0ZCWDI0VC9kbC92bWltYWdlLw== filename=MyJedomDelta-efi-aarch64-nba0.qcow2

* param_dl_err

This function will display help / manual and example on the command which calling it, depending of the "action" set by the calling function. This function also set variable "error=1". "error" variable content is always checked before each API execution, and if error=1, nothing happends and the lib exit cleanly. "action" are: 'add, enc, upd, show, del, mon, adv, log'. This function return error=1 when it has been called This function is mostly called by 'check_and_feed_dl_param' function

add_dl_task_api array_of_strings*

This function will add a download task BUT DOES NOT urlencode parameters. For the freebox accept the request and for the action of adding a download task work, you must specify '--data-urlencode' option before ALL of the different parameters you pass to the function

Example
add_dl_task_api
task parameters missing !

ERROR: all <param> for "add_dl_task_api" must be preceded by '--data-urlencode' and must be some of:
download_url=       # URL to download
hash=           # URL of hash file - hash format: MD5SUMS SHAxxxSUMS file or file.md5 or file.shaXXX 
download_dir=       # Download directory (will be created if not exist)
filename=       # Name of downloaded file 
recursive=      # if set to 'true' download will be recursive
username=       # (Optionnal) remote URL username 
password=       # (Optionnal) remote URL password 
cookie1=        # (Optionnal) content of HTTP Cookie header - to pass session cookie 
cookie2=        # (Optionnal) second HTTP cookie 
cookie3=        # (Optionnal) third HTTP cookie

NOTE: minimum parameters to specify on cmdline to create a download task: 
download_url= 

EXAMPLE (simple):
add_dl_task_api --data-urlencode "download_url=https://images.jeedom.com/freebox/freeboxDelta.qcow2"

EXAMPLE (medium):
add_dl_task_api --data-urlencode "download_url=https://images.jeedom.com/freebox/freeboxDelta.qcow2" --data-urlencode "hash=https://images.jeedom.com/freebox/SHA256SUMS" --data-urlencode "download_dir=/FBX24T/dl/vmimage/" --data-urlencode "filename=MyJedomDelta-efi-aarch64-nba0.qcow2"

EXAMPLE (full):
add_dl_task_api --data-urlencode "download_url=https://my-private-mirror.net/freebox/MyPrivateFreeboxVM_Image.qcow2" --data-urlencode "hash=https://my-private-mirror.net/freebox/MyPrivateFreeboxVM_Image.qcow2.sha512" --data-urlencode "download_dir=/FBX24T/dl/vmimage/" --data-urlencode "filename=MyNewVMimage-efi-aarch64.qcow2" --data-urlencode "username=MyUserName" --data-urlencode "password=VerySecret" --data-urlencode "recursive=false" --data-urlencode cookie1="MyHTTPsessionCookie" --data-urlencode cookie2="MyStickysessionCookie" --data-urlencode cookie3="MyAuthTokenCookie"
Picture

add_dl

add_dl_task_api --data-urlencode "download_url=https://images.jeedom.com/freebox/freeboxDelta.qcow2" --data-urlencode "hash=https://images.jeedom.com/freebox/SHA256SUMS" --data-urlencode "download_dir=/FBX24T/dl/vmimage/" --data-urlencode "filename=MyJedomDelta-efi-aarch64-nba0.qcow2"
{"success":true,"result":{"id":476}}

enc_dl_task_api array_of_strings*

This function will add a download task AND urlencode parameters. See example in the output of the function (when called with no parameters) This function return 0 if successfull and 1 otherwise

Example
enc_dl_task_api
task parameters missing !

ERROR: <param> for "enc_dl_task_api" must be some of:
download_url=       # URL to download
hash=           # URL of hash file - hash format: MD5SUMS SHAxxxSUMS file or file.md5 or file.shaXXX 
download_dir=       # Download directory (will be created if not exist)
filename=       # Name of downloaded file 
recursive=      # if set to 'true' download will be recursive
username=       # (Optionnal) remote URL username 
password=       # (Optionnal) remote URL password 
cookie1=        # (Optionnal) content of HTTP Cookie header - to pass session cookie 
cookie2=        # (Optionnal) second HTTP cookie 
cookie3=        # (Optionnal) third HTTP cookie

NOTE: minimum parameters to specify on cmdline to create a download task: 
download_url= 

EXAMPLE (simple):
enc_dl_task_api download_url="https://images.jeedom.com/freebox/freeboxDelta.qcow2"

EXAMPLE (medium):
enc_dl_task_api download_url="https://images.jeedom.com/freebox/freeboxDelta.qcow2" hash="https://images.jeedom.com/freebox/SHA256SUMS" download_dir="/FBX24T/dl/vmimage/" filename="MyJedomDelta-efi-aarch64-nba0.qcow2"

EXAMPLE (full):
enc_dl_task_api download_url="https://my-private-mirror.net/freebox/MyPrivateFreeboxVM_Image.qcow2" hash="https://my-private-mirror.net/freebox/MyPrivateFreeboxVM_Image.qcow2.sha512" download_dir="/FBX24T/dl/vmimage/" filename="MyNewVMimage-efi-aarch64.qcow2" username="MyUserName" password="VerySecret" recursive="false" cookie1="MyHTTPsessionCookie" cookie2="MyStickysessionCookie" cookie3="MyAuthTokenCookie"
Picture

enc_dl

enc_dl_task_api download_url="https://images.jeedom.com/freebox/freeboxDelta.qcow2" hash="https://images.jeedom.com/freebox/SHA256SUMS" download_dir="/FBX24T/dl/vm0/" filename="MyJedomDelta-efi-aarch64-nba0.qcow2"
{"success":true,"result":{"id":477}}
show_dl_task_api 477
                    SHOW DOWNLOADS TASK: 

------------------------------------------------------------------------------------------------------------------------
id: 477 queue_pos: 12       timestamp: 20230109-10:54:44    size: 2 GB  %in: 3 %    %out: 100 %
    status: downloading I/O: normal path: /FBX24T/dl/vm0/
    error: none     end-in: 654s    name: MyJedomDelta-efi-aarch64-nba0.qcow2
------------------------------------------------------------------------------------------------------------------------
Picture

enc_dlshow

* list_dl_task_api

This function will list all download tasks and display result in a pretty human readable format.

Example
list_dl_task_api

                    LIST OF DOWNLOADS TASKS:

------------------------------------------------------------------------------------------------------------------------
id: 256 queue_pos: 1        timestamp: 20221206-22:24:50    size: 9 GB  %in: 100 %  %out: 100 %
    status: done        I/O: normal path: /FBX24T/dl
    error: none     end-in: 0s  name: delta-10G-N.tar.gz
------------------------------------------------------------------------------------------------------------------------
id: 335 queue_pos: 2        timestamp: 20221223-15:32:13    size: 1 GB  %in: 0 %    %out: 100 %
    status: error       I/O: normal path: [error:no_download_dir_availiable]
    error: http_4xx     end-in: 0s  name: CentOS-8-GenericCloud-8.4.2105-20210603.0.aarch64.qcow2
------------------------------------------------------------------------------------------------------------------------
id: 435 queue_pos: 3        timestamp: 20221227-19:59:09    size: 290 MB    %in: 100 %  %out: 100 %
    status: done        I/O: normal path: /FBX24T/dl/vm6
    error: none     end-in: 0s  name: deb11-arm64.qcow2
------------------------------------------------------------------------------------------------------------------------
id: 436 queue_pos: 4        timestamp: 20221228-12:05:25    size: 500 MB    %in: 0 %    %out: 100 %
    status: error       I/O: normal path: L0ZCWDI0VC9kbA==
    error: http_4xx     end-in: 0s  name: delta-opensuze-N85.qcow2
------------------------------------------------------------------------------------------------------------------------
id: 449 queue_pos: 5        timestamp: 20221229-10:27:42    size: 9 GB  %in: 100 %  %out: 100 %
    status: done        I/O: high   path: /FBX24T/dl/vm0
    error: none     end-in: 0s  name: delta-10G-8.tar.gz
------------------------------------------------------------------------------------------------------------------------
id: 450 queue_pos: 6        timestamp: 20221229-10:42:32    size: 9 GB  %in: 100 %  %out: 100 %
    status: done        I/O: high   path: /FBX24T/dl/vm0
    error: none     end-in: 0s  name: delta-10G-9.tar.gz
------------------------------------------------------------------------------------------------------------------------
...
Picture

list_dl

show_dl_task_api integer*

This function will show a particular download task and display result in a pretty human readable format.

Example
show_dl_task_api 

ERROR: <param> must be :
id

NOTE: you can get a list of download tasks (showing all 'id'), just run: 
list_dl_task_api

EXAMPLE:
show_dl_task_api 450
Picture

show0_dl

show_dl_task_api 450

                    SHOW DOWNLOADS TASK: 

------------------------------------------------------------------------------------------------------------------------
id: 450 queue_pos: 6        timestamp: 20221229-10:42:32    size: 9 GB  %in: 100 %  %out: 100 %
    status: done        I/O: high   path: /FBX24T/dl/vm0
    error: none     end-in: 0s  name: delta-10G-9.tar.gz
------------------------------------------------------------------------------------------------------------------------
Picture

show_dl

upd_dl_task_api array_of_strings*

This function will update a download task. You can change the disk IO priority, the queue position of the concerned download task and you can also modify the status of the task. Valid status are : stopped, downloading, queued, retry NOTE: "stopped" pause the download task and "downloading" restart it where "retry" retried a failed task

Example
upd_dl_task_api 

ERROR: <param> for "upd_dl_task_api" must be some of:
id          # Task id: MUST be a number
io_priority=        # Disk IO priority: high normal or low
status=         # Status action: stopped or downloading or queued or retry
queue_pos=      # Task position in queue - 1= immediate download

NOTE: minimum parameters to specify on cmdline to update a download task: 
id 
io_priority= or/and status= or/and queue_pos= 

EXAMPLE:
upd_dl_task_api 15 io_priority="high" queue_pos="1" status="retry"
Picture

upd_dl

Example

Here we will update the download task #478: We will modify io_priority from "normal" to "high" First, constat the io_priority of task 478 with function show_dl_task_api

show_dl_task_api 478 
                    SHOW DOWNLOADS TASK: 

------------------------------------------------------------------------------------------------------------------------
id: 478 queue_pos: 13       timestamp: 20230110-16:28:48    size: 9 GB  %in: 26 %   %out: 100 %
    status: downloading I/O: normal path: /FBX24T/dl/vm0
    error: none     end-in: 43s name: delta-10G-881.tar.gz
------------------------------------------------------------------------------------------------------------------------
Picture

upd_dl_n

Now we will update the 'io_priority' of the task:

upd_dl_task_api 478 io_priority="high"

operation completed: 
{"success":true}

result:
{"rx_bytes":5260000000,"tx_bytes":0,"download_dir":"L0ZCWDI0VC9kbC92bTA=","archive_password":"","eta":26,"status":"downloading","io_priority":"high","type":"http","piece_length":0,"queue_pos":13,"id":478,"info_hash":"","created_ts":1673364528,"stop_ratio":0,"tx_rate":0,"name":"delta-10G-881.tar.gz","tx_pct":10000,"rx_pct":5260,"rx_rate":177610000,"error":"none","size":10000000000}
Picture

upd_dl_u

And now, constat that the 'io_priority' property had been updated with function show_dl_task_api:

show_dl_task_api 478 
                    SHOW DOWNLOADS TASK: 

------------------------------------------------------------------------------------------------------------------------
id: 478 queue_pos: 13       timestamp: 20230110-16:28:48    size: 9 GB  %in: 58 %   %out: 100 %
    status: downloading I/O: high   path: /FBX24T/dl/vm0
    error: none     end-in: 24s name: delta-10G-881.tar.gz
------------------------------------------------------------------------------------------------------------------------
Picture

upd_dl_h

monitor_dl_task_api integer*

This function will monitor a download task. The monitoring output is a line by line output (not dynamic) which is very convinient for scripting as it logs monitoring values to stdout line by line (can easyly be redirected to a file) NOTE: if using function login_freebox to connect the API, this function can automatically relogin the API if the monitoring task is longer than the session timeout (~1800s) NOTE: This function is for scripting, for direct use or for use in a terminal, please use function 'monitor_dl_task_adv_api'

Example
monitor_dl_task_api

ERROR: <param> must be :
id

NOTE: you can get a list of download tasks (showing all 'id'), just run: 
list_dl_task_api

EXAMPLE:
monitor_dl_task_api 53
Picture

mon-dl

Example
monitor_dl_task_api 472
task 472 downloading 0 MB/s, 0/MB 0% ... 
task 472 downloading 85 MB/s, 170/9536MB 1% ... 
task 472 downloading 150 MB/s, 750/9536MB 7% ... 
task 472 downloading 159 MB/s, 1268/9536MB 13% ... 
task 472 downloading 164 MB/s, 1802/9536MB 18% ... 
task 472 downloading 162 MB/s, 2269/9536MB 23% ... 
task 472 downloading 164 MB/s, 2784/9536MB 29% ... 
task 472 downloading 162 MB/s, 3252/9536MB 34% ... 
task 472 downloading 160 MB/s, 3786/9536MB 39% ... 
task 472 downloading 160 MB/s, 4301/9536MB 45% ... 
task 472 downloading 162 MB/s, 4854/9536MB 50% ... 
task 472 downloading 163 MB/s, 5340/9536MB 56% ... 
task 472 downloading 160 MB/s, 5798/9536MB 60% ... 
task 472 downloading 166 MB/s, 6389/9536MB 67% ... 
task 472 downloading 165 MB/s, 6904/9536MB 72% ... 
task 472 downloading 167 MB/s, 7448/9536MB 78% ... 
task 472 downloading 166 MB/s, 7963/9536MB 83% ... 
task 472 downloading 164 MB/s, 8430/9536MB 88% ... 
task 472 downloading 170 MB/s, 8993/9536MB 94% ... 
task 472 checking 163 MB/s, 9450/9536MB 99% ... 
task 472 checking 9536MB 3% ... 
task 472 checking 9536MB 30% ... 
task 472 checking 9536MB 49% ... 
task 472 checking 9536MB 55% ... 
task 472 checking 9536MB 63% ... 
task 472 checking 9536MB 66% ... 
task 472 checking 9536MB 69% ... 
task 472 checking 9536MB 74% ... 
task 472 checking 9536MB 76% ... 
task 472 checking 9536MB 79% ... 
task 472 checking 9536MB 83% ... 
task 472 checking 9536MB 86% ... 
task 472 checking 9536MB 89% ... 
task 472 checking 9536MB 92% ... 
task 472 checking 9536MB 94% ... 
task 472 done 9536MB 100% ... 
task 472 done !
Picture

mon_dl_out

monitor_dl_task_adv_api integer*

This function will monitor a download task. The monitoring output is a dynamic progress bar which is very convinient for tty usage NOTE: if using function login_freebox to connect the API, this function can automatically relogin the API if the monitoring task is longer than the session timeout (~1800s) NOTE: This function is for use in a terminal, the progress bar autoscale to the terminal width. Perfect for direct usage

Example
monitor_dl_task_adv_api

ERROR: <param> must be :
id

NOTE: you can get a list of download tasks (showing all 'id'), just run: 
list_dl_task_api

EXAMPLE:
monitor_dl_task_adv_api 53
Picture

mon_dl_adv

Example
monitor_dl_task_adv_api 473

task 473 downloading ... 
|...........................................................................................................| 100 % 0 MB/s 9536/9536MB 
task 473 checking ... 
|...........................................................................................................| 100 % checking ... 
task 473 done ...
Picture

downloading prog-bar-run

checking prog-chk

finished prog-done

del_dl_task_api integer*

This function will delete a download task. NOTE: You must delete finished download tasks, no interrest to keep a list of finished tasks

Example
del_dl_task_adv_api
ERROR: <param> must be :
id

NOTE: you can get a list of download tasks (showing all 'id'), just run: 
list_dl_task_api

EXAMPLE:
del_dl_task_api 53
Picture

del_dl

Example
del_dl_task_api 473
Sucessfully delete task #473: {"success":true}
Picture

del_dl_ok

dl_task_log_api integer*

This function will print a download task log NOTE: "info" level logs are in lightblue and "error" level log messages are printed in red

Example
dl_task_log_api
ERROR: <param> must be :
id

NOTE: you can get a list of download tasks (showing all 'id'), just run: 
list_dl_task_api

EXAMPLE:
dl_task_log_api 53
Picture

dl_log

Example
dl_task_log_api 473

2023-01-07 12:10:27 info: start url https://ipv4.paris.testdebit.info/10G/10G.tar.gz (crawling: 1)
2023-01-07 12:10:27 dbg: host resolved to 89.84.1.194:443
2023-01-07 12:10:27 dbg: connecting to remote host...
2023-01-07 12:10:27 dbg: connected
2023-01-07 12:10:27 dbg: sending request headers:
2023-01-07 12:10:27 dbg:    User-Agent: Mozilla/5.0
2023-01-07 12:10:27 dbg:    Host: ipv4.paris.testdebit.info:443
2023-01-07 12:10:27 dbg: request headers sent
2023-01-07 12:10:27 dbg: got response headers:
2023-01-07 12:10:27 dbg:    Upgrade: h2,h2c
2023-01-07 12:10:27 dbg:    Server: Apache
2023-01-07 12:10:27 dbg:    Last-Modified: Sat, 09 Oct 2021 22:00:00 GMT
2023-01-07 12:10:27 dbg:    ETag: 2540be400-5cdf29dfdf800
2023-01-07 12:10:27 dbg:    Date: Sat, 07 Jan 2023 11:10:27 GMT
2023-01-07 12:10:27 dbg:    Content-Type: application/x-gzip
2023-01-07 12:10:27 dbg:    Content-Length: 10000000000
2023-01-07 12:10:27 dbg:    Connection: Upgrade
2023-01-07 12:10:27 dbg:    Accept-Ranges: bytes
2023-01-07 12:10:27 info: unable to resume (missing content_range)
2023-01-07 12:10:27 dbg: receiving body
Picture

dl_log_inf

Example
nba@14RV-SERVER-159:~/fbxapi$ dl_task_log_api 335

Download Task log: task 335

2022-12-23 15:32:13 info: start url https://cloud.centos.org/centos/8/aarch64/images/CentOS-8-GenericCloud-8.4.2105-20210603.0.aarch64.qcow2 (crawling: 1)
2022-12-23 15:32:14 dbg: host resolved to 3.8.21.190:443
2022-12-23 15:32:14 dbg: connecting to remote host...
2022-12-23 15:32:14 dbg: connected
2022-12-23 15:32:14 dbg: sending request headers:
2022-12-23 15:32:14 dbg:    User-Agent: Mozilla/5.0
2022-12-23 15:32:14 dbg:    Host: cloud.centos.org:443
2022-12-23 15:32:14 dbg: request headers sent
2022-12-23 15:32:14 dbg: got response headers:
2022-12-23 15:32:14 dbg:    X-Xss-Protection: 1; mode=block
2022-12-23 15:32:14 dbg:    X-Frame-Options: SAMEORIGIN
2022-12-23 15:32:14 dbg:    X-Content-Type-Options: nosniff
2022-12-23 15:32:14 dbg:    Strict-Transport-Security: max-age=31536000
2022-12-23 15:32:14 dbg:    Server: Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips
2022-12-23 15:32:14 dbg:    Referrer-Policy: same-origin
2022-12-23 15:32:14 dbg:    Last-Modified: Thu, 03 Jun 2021 05:37:48 GMT
2022-12-23 15:32:14 dbg:    ETag: 4a2d0000-5c3d5f9b89a82
2022-12-23 15:32:14 dbg:    Date: Fri, 23 Dec 2022 14:32:14 GMT
2022-12-23 15:32:14 dbg:    Content-Type: application/octet-stream
2022-12-23 15:32:14 dbg:    Content-Length: 1244463104
2022-12-23 15:32:14 dbg:    Accept-Ranges: bytes
2022-12-23 15:32:14 err: failed to open //CentOS-8-GenericCloud-8.4.2105-20210603.0.aarch64.qcow2: Permission denied
2022-12-23 15:32:14 err: https://cloud.centos.org/centos/8/aarch64/images/CentOS-8-GenericCloud-8.4.2105-20210603.0.aarch64.qcow2 failed with code 418 OK
2022-12-23 15:32:14 dbg: receiving body
Picture

dl_log_err

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

DOWNLOAD API - EXTRA

LETS WRITE A SMALL PROGRAM FOR DOWNLOADING:

# Here my small program's name is 'tmon' like 'test monitoring download'
cat tmon
#!/bin/bash

# application credential:
MY_APP_ID="fbxvm"
MY_APP_TOKEN="Put-here-your-fbxvm-APP_TOKEN"

# source library and login
source ./fbx-delta-nba_bash_api.sh
login_freebox "$MY_APP_ID" "$MY_APP_TOKEN"

# variables:
download_dir="/FBX24T/dl/vm0"
download_url="https://ipv4.paris.testdebit.info/10G/10G.tar.gz" 
hash="https://master.3xo.fr/SHA512SUMS"
filename="delta-10G-505.tar.gz"

# MAIN PROGRAM:
answer=$(enc_dl_task_api download_url=${download_url} hash=${hash} download_dir=${download_dir} filename=${filename})
_check_success ${answer} || exit 1
colorize_output ${answer}
id=$(get_json_value_for_key "${answer}" result.id 2>/dev/null)
show_dl_task_api $id
monitor_dl_task_adv_api $id 
dl_task_log_api $id
show_dl_task_api $id
del_dl_task_api $id
echo

And now we'll just run this small program and let see the result and output: 

./tmon

operation completed: 
{"success":true}

result:
{"id":475}

                    SHOW DOWNLOADS TASK: 

------------------------------------------------------------------------------------------------------------------------
id: 475 queue_pos: 11       timestamp: 20230107-13:12:51    size: 9 GB  %in: 0 %    %out: 100 %
    status: downloading I/O: normal path: /FBX24T/dl/vm0
    error: none     end-in: 219s    name: delta-10G-506.tar.gz
------------------------------------------------------------------------------------------------------------------------

task 475 downloading ... 
|...............................................................................................................................................................| 100 % 0 MB/s 9536/9536MB 
task 475 checking ... 
|...............................................................................................................................................................| 100 % checking ... 
task 475 done ... 

Download Task log: task 475

2023-01-07 13:12:51 info: start url https://ipv4.paris.testdebit.info/10G/10G.tar.gz (crawling: 1)
2023-01-07 13:12:51 dbg: host resolved to 89.84.1.194:443
2023-01-07 13:12:51 dbg: connecting to remote host...
2023-01-07 13:12:51 dbg: connected
2023-01-07 13:12:51 dbg: sending request headers:
2023-01-07 13:12:51 dbg:    User-Agent: Mozilla/5.0
2023-01-07 13:12:51 dbg:    Host: ipv4.paris.testdebit.info:443
2023-01-07 13:12:51 dbg: request headers sent
2023-01-07 13:12:51 dbg: got response headers:
2023-01-07 13:12:51 dbg:    Upgrade: h2,h2c
2023-01-07 13:12:51 dbg:    Server: Apache
2023-01-07 13:12:51 dbg:    Last-Modified: Sat, 09 Oct 2021 22:00:00 GMT
2023-01-07 13:12:51 dbg:    ETag: 2540be400-5cdf29dfdf800
2023-01-07 13:12:51 dbg:    Date: Sat, 07 Jan 2023 12:12:51 GMT
2023-01-07 13:12:51 dbg:    Content-Type: application/x-gzip
2023-01-07 13:12:51 dbg:    Content-Length: 10000000000
2023-01-07 13:12:51 dbg:    Connection: Upgrade
2023-01-07 13:12:51 dbg:    Accept-Ranges: bytes
2023-01-07 13:12:51 info: unable to resume (missing content_range)
2023-01-07 13:12:51 dbg: receiving body

                    SHOW DOWNLOADS TASK: 

------------------------------------------------------------------------------------------------------------------------
id: 475 queue_pos: 11       timestamp: 20230107-13:12:51    size: 9 GB  %in: 100 %  %out: 100 %
    status: done        I/O: normal path: /FBX24T/dl/vm0
    error: none     end-in: 0s  name: delta-10G-506.tar.gz
------------------------------------------------------------------------------------------------------------------------

Sucessfully delete task #475: {"success":true}
Picture

tmon_dl

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API FRONTEND FUNCTIONS - DIRECT DOWNLOAD

local_direct_dl_api path*

This function will download a file from freebox NAS storage to your computer

Example
local_direct_dl_api

file_fullpath parameters missing !

you must provide /path/to/download/file on the cmdline !
Picture

l_dl2

Example
local_direct_dl_api /FBX24T/dl/vm1/vm11/delta-opensuze-ZN90.qcow2

Downloading file from Freebox to local directory:

/FBX24T/dl/vm1/vm11/delta-opensuze-ZN90.qcow2 ---> ./delta-opensuze-ZN90.qcow2
############################################################################################################################################################################################### 100,0%

Done: 
501M    delta-opensuze-ZN90.qcow2
Picture

l_direct_dl_ok2

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API FRONTEND FUNCTIONS - DOWNLOAD SHARE LINK

NOTE 1

To use this API, you must have a public URL and your "Freebox Remote Access" must be enabled in FreeboxOS

NOTE 2

When you post a share link on an internet forum, the target of the link become accessible for download to anyone which have access to this link and without any kind of authentication. Only files targed by the link become accessible.

USAGE EXAMPLE
WARNING

check_and_feed_share_link_param array_of_strings*

This function will check if the provided arguments are valid parameters for the function which is calling it depending of the "action" set by the calling function. If not, function param_share_link_err will be called to set error and display help for the command depending on "action" set by the calling function. "action" are: 'add, show, get, del'. This function return a 'json' object or an 'as it must be formated object for the command' to be passed to "API CALL" functions

Example
action=add
check_and_feed_share_link_param path=/FBX24T/dl/vm0/delta-10G-5.tar.gz expire=2023-12-10T10:00:00
echo -e  "${share_link_object}"
{"path":"L0ZCWDI0VC9kbC92bTAvZGVsdGEtMTBHLTUudGFyLmd6","expire":"1702198800"}

* param_share_link_err

This function will display help / manual and example on the command which calling it, depending of the "action" set by the calling function. This function also set variable "error=1". "error" variable content is always checked before each API execution, and if error=1, nothing happends and the lib exit cleanly. "action" are: 'add, get, show, del'. This function return error=1 when it has been called This function is mostly called by 'check_and_feed_share_link_param' function

* list_share_link

This function will list all download share links you have created on your Freebox

Example
list_share_link

                    LIST OF SHARED LINKS:

------------------------------------------------------------------------------------------------------------------------
token: nb5KRyH4TOeC07w8     expire: 2023-01-11 12:42:08 name: nba50g2.tar.xz
path: /FBX24T/dl/vm1/vm15/nba50g2.tar.xz
URL: https://fbx.my-public-domain.net:4011/share/nb5KRyH4TOeC07w8/nba50g2.tar.xz
------------------------------------------------------------------------------------------------------------------------
token: FfL2R2C1dhbk9Xj8     expire: 2023-01-11 12:49:17 name: nba50g.tar.gz
path: /FBX24T/dl/vm1/vm15/nba50g.tar.gz
URL: https://fbx.my-public-domain.net:4011/share/FfL2R2C1dhbk9Xj8/nba50g.tar.gz
------------------------------------------------------------------------------------------------------------------------
token: khR-1PGGwMjxQMrY     expire: 2023-01-11 12:53:14 name: nba20g.7z
path: /FBX24T/dl/vm1/vm14/nba20g.7z
URL: https://fbx.my-public-domain.net:4011/share/khR-1PGGwMjxQMrY/nba20g.7z
------------------------------------------------------------------------------------------------------------------------
token: rLri0H5Sgbr3O-k5     expire: 2023-12-12 10:10:10 name: delta-10G-1.tar.gz
path: /FBX24T/dl/vm0/delta-10G-1.tar.gz
URL: https://fbx.my-public-domain.net:4011/share/rLri0H5Sgbr3O-k5/delta-10G-1.tar.gz
------------------------------------------------------------------------------------------------------------------------
token: bq2Lw-bh8FCbIM3b     expire: 2023-10-11 00:00:00 name: delta-10G-2.tar.gz
path: /FBX24T/dl/vm0/delta-10G-2.tar.gz
URL: https://fbx.my-public-domain.net:4011/share/bq2Lw-bh8FCbIM3b/delta-10G-2.tar.gz
------------------------------------------------------------------------------------------------------------------------
token: l1i-SuYthQC8bjKo     expire: 2023-10-01 01:00:00 name: delta-10G-3.tar.gz
path: /FBX24T/dl/vm0/delta-10G-3.tar.gz
URL: https://fbx.my-public-domain.net:4011/share/l1i-SuYthQC8bjKo/delta-10G-3.tar.gz
------------------------------------------------------------------------------------------------------------------------
token: S3VGVZ5b9vJvKAe-     expire: 1970-01-01 01:00:00 name: delta-10G-4.tar.gz
path: /FBX24T/dl/vm0/delta-10G-4.tar.gz
URL: https://fbx.my-public-domain.net:4011/share/S3VGVZ5b9vJvKAe-/delta-10G-4.tar.gz
------------------------------------------------------------------------------------------------------------------------
token: vQdJMkmfznzwnbV7     expire: 2023-10-11 00:00:00 name: delta-10G-6.tar.gz
path: /FBX24T/dl/vm0/delta-10G-6.tar.gz
URL: https://fbx.my-public-domain.net:4011/share/vQdJMkmfznzwnbV7/delta-10G-6.tar.gz
------------------------------------------------------------------------------------------------------------------------
token: L1hsYOX1JpVeX9hF     expire: 2023-12-10 10:00:00 name: delta-10G-5.tar.gz
path: /FBX24T/dl/vm0/delta-10G-5.tar.gz
URL: https://fbx.my-public-domain.net:4011/share/L1hsYOX1JpVeX9hF/delta-10G-5.tar.gz
------------------------------------------------------------------------------------------------------------------------
Picture

list_shl

show_share_link string*

This function will show a particular share link, specified by the "token" you provide as the first and only parameter of the command line This function has a Human Readable output, and is made to run in a terminal

Example
show_share_link

ERROR: <param> must be :
token           # token is a chain of 16 alphanumeric or punctuation characters

NOTE: you can get a list of share_link token (showing all 'token'), just run: 
list_share_link

EXAMPLE:
show_share_link "nb5KDjU9TOeC00w3"
Picture

sh_sl

Example
show_share_link l1i-SuYthQC8bjKo 
                    SHOW LINK TOKEN: l1i-SuYthQC8bjKo

------------------------------------------------------------------------------------------------------------------------
token: l1i-SuYthQC8bjKo     expire: 2023-10-01 01:00:00 name: delta-10G-3.tar.gz
path: /FBX24T/dl/vm0/delta-10G-3.tar.gz
URL: https://fbx.my-public-domain.net:4011/share/l1i-SuYthQC8bjKo/delta-10G-3.tar.gz
------------------------------------------------------------------------------------------------------------------------
Picture

sh_sltk

get_share_link string*

This function will show a particular share link, specified by the "token" you provide as the first and only parameter of the command line This function has a JSON output which can be easyly parse by a computer or another program The purpose of this function is to have "machine" output of the share link for use in other programs

Example
get_share_link

ERROR: <param> must be :
token           # token is a chain of 16 alphanumeric or punctuation characters

NOTE: you can get a list of share_link token (showing all 'token'), just run: 
list_share_link

EXAMPLE:
get_share_link "nb5KDjU9TOeC00w3"
Picture

g_sl_r

Example
get_share_link l1i-SuYthQC8bjKo

operation completed: 
{"success":true}

result:
{"path":"L0ZCWDI0VC9kbC92bTAvZGVsdGEtMTBHLTMudGFyLmd6","token":"l1i-SuYthQC8bjKo","name":"delta-10G-3.tar.gz","expire":1696114800,"fullurl":"https://fbx.my-public-domain.net:4011/share/l1i-SuYthQC8bjKo/delta-10G-3.tar.gz","internal":0}
Picture

g_sl

add_share_link array_of_strings*

This function will add a share link and will return a json containing the share link "token" which idendtify this share link on your Freebox This function has a JSON output which can be easyly parse by a computer or another program

Example
add_share_link

ERROR: <param> must be :
path=           # fullpath of file or dir to share 
expire=         # expire date: 0=never - format yyyy-mm-dd - to specify time add: Thh:mm:ss

NOTE: minimum parameters to specify on cmdline to add a share_link: 
path= 
expire= 

EXAMPLE:
add_share_link path="/MyFBX/dl/debian-vm-12.qcow2" expire="2023-12-12T22:33:44"
Picture

a_sl_r

add_share_link path=/FBX24T/dl/vm0/delta-10G-5.tar.gz expire=2024-01-08T10:00:00 
operation completed: 
{"success":true}

result:
{"path":"L0ZCWDI0VC9kbC92bTAvZGVsdGEtMTBHLTUudGFyLmd6","token":"UQttle1mcziV2b9f","name":"delta-10G-5.tar.gz","expire":1704704400,"fullurl":"https://fbx.my-public-domain.net:4011/share/UQttle1mcziV2b9f/delta-10G-5.tar.gz","internal":0}
Picture

a_sl

del_share_link string*

This function will del a share link and will return a json containing the success result This function take the 'share link token' as argument

Example
del_share_link

ERROR: <param> must be :
token           # token is a chain of 16 alphanumeric or punctuation characters

NOTE: you can get a list of share_link token (showing all 'token'), just run: 
list_share_link

EXAMPLE:
del_share_link "nb5KDjU9TOeC00w3"
Picture

del_sl_r

Example
del_share_link UQttle1mcziV2b9f

operation completed: 
{"success":true}
Picture

del_sl

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API FRONTEND FUNCTIONS - NETWORK: DHCP

WARNING

To use these functions, your application which login the API MUST be granted to modify your box setup parameters (from freeboxOS web interface, see: GRANT API ACCESS)

check_and_feed_dhcp_param array_of_strings*

This function will check if the provided arguments are valid parameters for the function which is calling it depending of the "action" set by the calling function. If not, function param_dhcp_err will be called to set error and display help for the command depending on "action" set by the calling function. "action" are: 'add, upd, del'. This function return a 'json' object to be passed to "API CALL" functions. This function also check the validity of IP adress (must be RFC1918 ip address) and validity of MAC address format using ':' (column) as separator, so the help / error output also contain an error message if IP or MAC address has a bad format

Example
action=add
check_and_feed_dhcp_param mac="00:01:02:03:04:05" ip="192.168.123.123" comment="VM: 14RV-FSRV-123"
echo -e  "${dhcp_object}"
{"mac":"00:01:02:03:04:05","ip":"192.168.123.123","comment":"VM: 14RV-FSRV-123"}

* param_dhcp_err

This function will display help / manual and example on the command which calling it, depending of the "action" set by the calling function. This function also set variable "error=1". "error" variable content is always checked before each API execution, and if error=1, nothing happends and the lib exit cleanly. "action" are: 'add, upd, del'. This function return error=1 when it has been called This function is mostly called by 'check_and_feed_dhcp_param' function

* list_dhcp_static_lease

This function list DHCP static leases and will show leases usage status (show if machine is online or offline)

Example
list_dhcp_static_lease
                DHCP ASSIGNED STATIC LEASES:

#:      id:         mac:            ip:         state:      hostname:
0:  3C:FD:FE:1A:66:40   3C:FD:FE:1A:66:40   192.168.100.25      offline     14RV-SERVER-SFP0
1:  00:E0:81:D6:AE:B5   00:E0:81:D6:AE:B5   192.168.100.26      offline     14RV-SERVER-NBA0
2:  00:01:02:03:B4:11   00:01:02:03:B4:11   192.168.100.41      offline     00:01:02:03:B4:11
3:  00:01:02:03:04:12   00:01:02:03:04:12   192.168.100.42      offline     00:01:02:03:04:12
4:  00:01:42:33:34:33   00:01:42:33:34:33   192.168.100.43      offline     00:01:42:33:34:33
5:  00:01:02:03:14:20   00:01:02:03:14:20   192.168.100.44      offline     00:01:02:03:14:20
6:  60:F2:62:B6:93:1F   60:F2:62:B6:93:1F   192.168.100.55      offline     lap-nba
7:  14:DD:A9:D3:E8:B6   14:DD:A9:D3:E8:B6   192.168.100.59      offline     14RV-BMC
8:  14:DD:A9:D3:E8:B7   14:DD:A9:D3:E8:B7   192.168.100.79      offline     14RV-SERVER-BMC-SHARED
9:  34:27:92:80:29:7C   34:27:92:80:29:7C   192.168.100.88      online      14RV-DEVIALET
10: 8C:97:EA:55:BB:B6   8C:97:EA:55:BB:B6   192.168.100.89      online      14RV-FBXAP
11: 28:16:AD:09:43:63   28:16:AD:09:43:63   192.168.100.94      offline     14RV-ULTRA-wifi
12: 38:AF:29:55:D3:0E   38:AF:29:55:D3:0E   192.168.100.95      online      14RV-CAM
13: 34:27:92:E5:76:96   34:27:92:E5:76:96   192.168.100.96      online      14RV-FBXCAM
14: 8C:DC:D4:C9:13:A1   8C:DC:D4:C9:13:A1   192.168.100.100     offline     14RV-PRINTER
15: 24:5E:BE:43:B3:73   24:5E:BE:43:B3:73   192.168.100.123     offline     lap-nba-sfp+
16: E0:23:FF:3F:A6:CC   E0:23:FF:3F:A6:CC   192.168.100.250     offline     14RV-FW101F
Picture

list_dhcp

add_dhcp_static_lease array_of_strings*

This function simply add a DHCP static leases

Example
add_dhcp_static_lease

ERROR: <param> for add_dhcp_static_lease must be some of:
mac=
ip=
comment=

NOTE: minimum parameters to specify on cmdline to create a static DHCP lease: 
mac= 
ip=

EXAMPLE:
add_dhcp_static_lease mac="00:01:02:03:04:05" ip="192.168.123.123" comment="VM: 14RV-FSRV-123"

operation failed ! 
Adresse mac invalide: invalid_request
Picture

add_dhcp_r

Example
add_dhcp_static_lease mac=00:01:02:03:04:05 ip=192.168.100.46 comment="DHCP example for this README"

operation completed: 
{"success":true}

result:
{"mac":"00:01:02:03:04:05","comment":"DHCP example for this README","hostname":"00:01:02:03:04:05","id":"00:01:02:03:04:05","ip":"192.168.100.46"}
Picture

add_dhcp

Now we will verify that our DHCP static lease had successfully be added : Note that I'm using here '--color=never' option of 'grep' because I want to keep the library formatting for the picture. 

list_dhcp_static_lease | grep --color=never '00:01:02:03:04:05'
6:      00:01:02:03:04:05       00:01:02:03:04:05       192.168.100.46          offline         00:01:02:03:04:05
Picture

ad_dh_g

upd_dhcp_static_lease array_of_strings*

This function update a DHCP static leases mac= parameter is mandatory

Example
upd_dhcp_static_lease 

ERROR: <param> for upd_dhcp_static_lease must be some of:
mac=
ip=
comment=

NOTE: minimum parameters to specify on cmdline to update a static DHCP lease: 
mac= 
ip=  or comment= 

EXAMPLE:
upd_dhcp_static_lease mac="00:01:02:03:04:05" ip="192.168.123.123" comment="VM: 14RV-FSRV-123"

operation failed ! 
Requête invalide (404): invalid_request
Picture

upd_dhcp_r

Example
upd_dhcp_static_lease mac=00:01:02:03:04:05 ip=192.168.100.47 comment="DHCP example for this README"

operation completed: 
{"success":true}

result:
{"mac":"00:01:02:03:04:05","comment":"DHCP example for this README","hostname":"00:01:02:03:04:05","id":"00:01:02:03:04:05","ip":"192.168.100.47"}
Picture

upd_dhcp

And now we can verify that the IP address of this DHCP static lease had been successfully update from 192.168.100.46 to 192.168.100.47

list_dhcp_static_lease | grep --color=never '00:01:02:03:04:05'
6:  00:01:02:03:04:05   00:01:02:03:04:05   192.168.100.47      offline     00:01:02:03:04:05
Picture

upd_dhcp_ok

del_dhcp_static_lease string*

This function simply del a DHCP static leases. It takes the DHCP lease MAC address as 'id' argument.

Example
del_dhcp_static_lease 

ERROR: <param> must be :
id

NOTE: you can get a list of DHCP static lease (showing all 'id'), just run : 
list_dhcp_static_lease

EXAMPLE:
del_dhcp_static_lease 00:01:02:03:04:05

ERROR: Bad value for id, id must have a mac address format:
00:01:02:03:04:05

operation failed ! 
Error in 'id' mac address format
Picture

del_dhcp_r

Example
del_dhcp_static_lease 00:01:02:03:04:05             

operation completed: 
{"success":true}
Picture

del_dhcp

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API FRONTEND FUNCTIONS - NETWORK: NAT REDIRECTIONS

WARNING

To use these functions, your application which login the API MUST be granted to modify your box setup parameters (from freeboxOS web interface, see: GRANT API ACCESS)

WARNING

Today, when your connection is in ROUTER MODE, Free Telecom from Iliad Group often deliver your internet connection with 1 fixed public IP shared for 4 people and ISP NAT 25% of the availiable ports of the shared public IP adress to each of the 4 customer's connection.

If you are in this case and this situation is convinient for you (maybe you have ports from 1 to 16384), you must BE CAREFULL when adding or modifying destination NAT redirection that the NAT redirection you want to add / modify is not out of your assigned port range

If this situation is not convinient for you, see how to get a full-stack IP address with all ports (Free of charges, see: FULL-STACK IPV4)

check_and_feed_fw_redir_param array_of_strings*

This function will check if the provided arguments are valid parameters for the function which is calling it depending of the "action" set by the calling function. If not, function param_fw_redir_err will be called to set error and display help for the command depending on "action" set by the calling function. "action" are: 'add, upd, del, ena, dis'. This function return a 'json' object to be passed to "API CALL" functions. This function also check the validity of IP adress, of local IP address (must be RFC1918 ip address) and validity of MAC address format using ':' (column) as separator, so the help / error output also contain an error message if IP or MAC address has a bad format

Example
action=add
check_and_feed_fw_redir_param  wan_port_start="443" lan_port="443" lan_ip="192.168.133.43" ip_proto="tcp"
echo -e ${fw_redir_object}
{"wan_port_start":"443","lan_port":"443","lan_ip":"192.168.133.43","ip_proto":"tcp","wan_port_end":"443","src_ip":"0.0.0.0","enabled":"1"}

* param_fw_redir_err

This function will display help / manual and example on the command which calling it, depending of the "action" set by the calling function. This function also set variable "error=1". "error" variable content is always checked before each API execution, and if error=1, nothing happends and the lib exit cleanly. "action" are: 'add, upd, del, ena, dis'. This function return error=1 when it has been called This function is mostly called by 'check_and_feed_fw_redir_param' function

* list_fw_redir

This function list destination NAT redirections and will show the status (if the redirection is enabled or if it's currently disabled).

Example
list_fw_redir

                NETWORK INCOMMING NAT REDIRECTIONS:

#:  id: lan-port:   protocol:   lan_ip:         wan-port-range:     allowed-ip  state:      hostname:
0:  1   443     tcp     192.168.133.250     444 444     0.0.0.0     active      14RV-FW101F-cluster
1:  2   22      tcp     192.168.133.250     422 422     0.0.0.0     active      14RV-FW101F-cluster
2:  3   500     udp     192.168.133.248     500 500     0.0.0.0     active      14RV-FW101F-cluster
3:  4   4500        udp     192.168.133.248     4500    4500        0.0.0.0     active      14RV-FW101F-cluster
4:  5   8443        tcp     192.168.133.250     8443    8443        0.0.0.0     active      14RV-FW101F-cluster
5:  6   9443        tcp     192.168.133.1       9443    9443        0.0.0.0     active      14RV-FW90D
6:  8   9001        tcp     192.168.133.229     9001    9001        0.0.0.0     active      192.168.133.229
7:  9   80      tcp     192.168.133.227     80  80      0.0.0.0     active      192.168.133.227
8:  10  443     tcp     192.168.133.227     443 443     0.0.0.0     active      192.168.133.227
9:  11  22      tcp     192.168.133.227     222 222     0.0.0.0     active      192.168.133.227
10: 12  9030        tcp     192.168.133.229     9030    9030        0.0.0.0     disabled    192.168.133.229
11: 13  37777       tcp     192.168.133.230     37777   37777       0.0.0.0     disabled    192.168.133.230
12: 14  443     tcp     192.168.133.1       4444    4444        0.0.0.0     disabled    14RV-FW90D
13: 15  22      tcp     192.168.133.1       4422    4422        0.0.0.0     disabled    14RV-FW90D
14: 16  80      tcp     192.168.133.250     8080    8080        0.0.0.0     disabled    14RV-FW101F-cluster
15: 17  22      tcp     192.168.133.60      443 443     0.0.0.0     disabled    14RV-FBXSRV-02
16: 30  22      tcp     192.168.133.225     22  22      0.0.0.0     active      192.168.133.225
17: 74  61078       tcp     192.168.133.36      61078   61078       44.33.11.22     active      192.168.133.36
18: 66  61066       tcp     192.168.133.38      61066   61066       0.0.0.0     disabled    192.168.133.38
19: 67  61067       tcp     192.168.133.38      61067   61067       0.0.0.0     disabled    192.168.133.38
20: 72  61073       tcp     192.168.133.44      61073   61073       55.44.33.22     active      192.168.133.44
21: 73  61076       tcp     192.168.133.46      61076   61076       77.77.77.77     active      192.168.133.46
Picture

list_fw_redir

add_fw_redir array_of_strings*

This function add a destination NAT redirection from a port of your public IP to a port of a local ip address on your local network. It's also possible to specify ports range When using port ranges, there is no options to specify the 'lan last port' because it's automatically calculated by the API : (last port is lan_port + wan_port_end - wan_port_start)

Example
add_fw_redir

ERROR: <param> for "add_fw_redir" must be some of:
lan_port=       # lan start port: must be a number in [1-65535]
wan_port_start=     # wan start port: must be a number in [1-65535]
wan_port_end=       # wan end port: must be a number in [1-65535]
lan_ip=         # local destination ip
ip_proto=       # must be: 'tcp' or 'udp'
src_ip=         # allowed ip: default: all ip allowed
enabled=        # boolean 'true' or 'false': default 'true'
comment=        # string: maximum 63 char 

NOTE: minimum parameters to specify on cmdline to create a destination NAT redirection: 
wan_port_start= 
lan_port= 
lan_ip= 
ip_proto=

WARNING: if not specified on cmdline following parameters will be reset to their default values
wan_port_end=       # default value: wan_port_start
src_ip=         # default: all ip allowed: 0.0.0.0
enabled=        # default: true

EXAMPLE: (simple)
add_fw_redir wan_port_start="443" lan_port="443" lan_ip="192.168.123.123" ip_proto="tcp" comment="NAT: destination nat: HTTPS to VM 14RV-FSRV-123:HTTPS"

EXAMPLE: (full)
add_fw_redir wan_port_start="60000" wan_port_end="60010" lan_port="60000" lan_ip="192.168.123.123" ip_proto="tcp" src_ip="22.22.22.22" enabled="true" comment="NAT: destination nat: PASV_FTP to VM 14RV-FSRV-123:FTP_PASV"
Picture

a_fw_r

Example
add_fw_redir wan_port_start="1443" lan_port="443" lan_ip="192.168.133.47" ip_proto="tcp" comment="NAT: false HTTPS to VM 14RV-FSRV-47:HTTPS"

operation completed: 
{"success":true}

result:
{"enabled":true,"comment":"NAT: false HTTPS to VM 14RV-FSRV-47:HTTPS","id":75,"valid":true,"src_ip":"0.0.0.0","hostname":"192.168.133.47","lan_port":443,"wan_port_end":1443,"wan_port_start":1443,"lan_ip":"192.168.133.47","ip_proto":"tcp"}
Picture

a_fw

Now you can verify with the 'list_fw_redir' function

list_fw_redir | egrep --color=never '1443|port'
#:  id: lan-port:   protocol:   lan_ip:         wan-port-range:     allowed-ip  state:      hostname:
22: 75  443     tcp     192.168.133.47      1443    1443        0.0.0.0     active      192.168.133.47
Picture

a_fw_ok

upd_fw_redir array_of_strings*

This function update an existant destination NAT redirection. Port range, status allowed-ip (parameter name: src_ip) and lan destination ip address can be updated.

Example
upd_fw_redir

ERROR: <param> for "upd_fw_redir" must be some of:
id=         # id: must be a number: id of nat rule to modify
lan_port=       # lan start port: must be a number in [1-65535]
wan_port_start=     # wan start port: must be a number in [1-65535]
wan_port_end=       # wan end port: must be a number in [1-65535]
lan_ip=         # local destination ip
ip_proto=       # must be: 'tcp' or 'udp'
src_ip=         # allowed ip: default all ip allowed
enabled=        # boolean 'true' or 'false': default 'true'
comment=        # string: maximum 63 char 

NOTE: please run "list_fw_redir" to get list of all rules 'id' 

NOTE: minimum parameters to specify on cmdline to update a destination NAT redirection: 
id=
wan_port_start=

WARNING: if not specified on cmdline following parameters will be reset to their default values
wan_port_end=       # default value: wan_port_start
src_ip=         # default: all ip allowed: 0.0.0.0
enabled=        # default: true

EXAMPLE: (simple)
upd_fw_redir id=34 wan_port_start="443" lan_port="443" lan_ip="192.168.123.123" comment="NAT: destination nat: HTTPS to VM 14RV-FSRV-123:HTTPS"

EXAMPLE: (full)
upd_fw_redir id=34 wan_port_start="60000" wan_port_end="60010" lan_port="60000" lan_ip="192.168.123.123" comment="NAT: destination nat: FTP(S) PASIVE PORT to VM 14RV-FSRV-123:FTP_PASV"
Picture

upd_fw_r

Example
upd_fw_redir id=75 wan_port_start=1443 src_ip=88.77.66.55

operation completed: 
{"success":true}

result:
{"enabled":true,"comment":"NAT: false HTTPS to VM 14RV-FSRV-47:HTTPS","id":75,"valid":true,"src_ip":"88.77.66.55","hostname":"192.168.133.47","lan_port":443,"wan_port_end":1443,"wan_port_start":1443,"lan_ip":"192.168.133.47","ip_proto":"tcp"}
Picture

upd_fw

Now you can verify with the 'list_fw_redir' function that the redirection had been updated, allowed-ip change from 0.0.0.0 to 88.77.66.55

list_fw_redir | egrep --color=never '1443|port'
#:  id: lan-port:   protocol:   lan_ip:         wan-port-range:     allowed-ip  state:      hostname:
22: 75  443     tcp     192.168.133.47      1443    1443        88.77.66.55     active      192.168.133.47
Picture

upd_fw_ok

dis_fw_redir integer*

This function simply disable a previously created NAT redirection. This function take 'id' as argument. You can list all incoming NAT redirection and get a list of all 'id' with function 'list_fw_redir'.

Example
dis_fw_redir

ERROR: <param> for "dis_fw_redir" must be :
id          # id: must be a number

NOTE: please run  "list_fw_redir" to get list of all destination NAT redirection (showing all 'id'):
list_fw_redir

EXAMPLE:
dis_fw_redir 34
Picture

dis_fw_r

Example
dis_fw_redir 75

operation completed: 
{"success":true}

result:
{"enabled":false,"comment":"NAT: false HTTPS to VM 14RV-FSRV-47:HTTPS","id":75,"valid":true,"src_ip":"88.77.66.55","hostname":"192.168.133.47","lan_port":443,"wan_port_end":1443,"wan_port_start":1443,"lan_ip":"192.168.133.47","ip_proto":"tcp"}
Picture

dis_fw

Now you can verify with the 'list_fw_redir' function that the redirection had been disabled (state value is now 'disabled')

list_fw_redir | egrep --color=never '1443|port'
#:  id: lan-port:   protocol:   lan_ip:         wan-port-range:     allowed-ip  state:      hostname:
22: 75  443     tcp     192.168.133.47      1443    1443        88.77.66.55     disabled    192.168.133.47
Picture

dis_fw_o

ena_fw_redir integer*

This function simply enable a previously created NAT redirection. This function take 'id' as argument. You can list all incoming NAT redirection and get a list of all 'id' with function 'list_fw_redir'.

Example
ena_fw_redir

ERROR: <param> for "ena_fw_redir" must be :
id          # id: must be a number

NOTE: please run "list_fw_redir" to get list of all destination NAT redirection (showing all 'id'):
list_fw_redir

EXAMPLE:
ena_fw_redir 34
Picture

ena_fw_r

Example
ena_fw_redir 75

operation completed: 
{"success":true}

result:
{"enabled":true,"comment":"NAT: false HTTPS to VM 14RV-FSRV-47:HTTPS","id":75,"valid":true,"src_ip":"88.77.66.55","hostname":"192.168.133.47","lan_port":443,"wan_port_end":1443,"wan_port_start":1443,"lan_ip":"192.168.133.47","ip_proto":"tcp"}
Picture

ena_fw

Now you can verify with the 'list_fw_redir' function that the redirection had been enabled (state value is now 'active' again)

list_fw_redir | egrep --color=never '1443|port'
#:  id: lan-port:   protocol:   lan_ip:         wan-port-range:     allowed-ip  state:      hostname:
22: 75  443     tcp     192.168.133.47      1443    1443        88.77.66.55     active      192.168.133.47
Picture

ena_fw_o

del_fw_redir integer*

This function simply delete an incoming NAT redirection. This function take 'id' as argument. You can list all incoming NAT redirection and get a list of all 'id' with function 'list_fw_redir'.

Example
del_fw_redir

ERROR: <param> for "del_fw_redir" must be :
id          # id: must be a number

NOTE: please run "list_fw_redir" to get list of all destination NAT redirection (showing all 'id'):
list_fw_redir

EXAMPLE:
del_fw_redir 34
Picture

del_fw_r

Example
del_fw_redir 75

operation completed: 
{"success":true}
Picture

del_fw

Now you can verify with the 'list_fw_redir' function that the redirection had been suppressed but for changing, we will just try to delete the same redirection once again (this NAT redirection is already deleted). You can notice that the redirection does not exist anymore:

del_fw_redir 75

operation failed ! 
Impossible de supprimer la redirection : Entrée non trouvée: noent
Picture

del_fw_o

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API FRONTEND FUNCTIONS - FILESYSTEM

This API let you list and manage files and directory on Freebox storage. It also let you extract and create archives.

To be honest, we cannot work with 'share link api' or 'download api' or 'vm api' without having file and filesystem management.

Let's imagine the following scenario:

Just have a look on what differents tasks you will have to do with the API:

After you create, start and configure your VM (using fbxvm-ctrl prgram) you want to share the image with other Freebox Delta users

So it was required that simple tasks like ls, cp, mv, rm, mkdir were availiable in this library

When using this API, you will have to manage 'filesystem tasks' for one hand and in the other hand you will have to manage 'filesystem operations (actions)'

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

FILESYSTEM TASKS MANAGEMENT

check_and_feed_fs_task_param array_of_strings*

This function will check if the provided arguments are valid parameters for the function which is calling it depending of the "action" set by the calling function. If not, function param_fs_task_err will be called to set error and display help for the command depending on "action" set by the calling function. "action" are: 'hash, get, upd, show, del, mon'. This function will also check argument validity and return 0 if success or 1 if error. This function also return a json 'fs_task_param_object' to be passed as argument to api call function

Example
action=upd
check_and_feed_fs_task_param 215 state="paused"
echo -e "${fs_task_param_object}"
{"state":"paused"}

* param_fs_task_err

This function will display help / manual and example on the command which calling it, depending of the "action" set by the calling function. This function also set variable "error=1". "error" variable content is always checked before each API execution, and if error=1, nothing happends and the lib exit cleanly. "action" are: 'hash, get, upd, show, del, mon'. This function return error=1 when it has been called This function is mostly called by 'check_and_feed_fs_task_param' function

* list_fs_task

This function will simply list all filesystem tasks and also show the status of each task

Example
list_fs_task

                    LIST OF FILESYSTEM TASKS:

------------------------------------------------------------------------------------------------------------------------
id: 286 start: 20221230-17:58:34    end: 20221230-17:59:11  %progress: 100 %    size: 10032 MB
    status: done            time: 12s       from: /FBX24T/dl/vm1/delta-opensuze-N87.qcow2
    error: none         end-in: 0s      to:   /FBX24T/dl/vm1/vm10/delta-opensuze-N87.qcow2
    task type: cp           #files: 2       dst:  /FBX24T/dl/vm1/vm10
------------------------------------------------------------------------------------------------------------------------
id: 288 start: 20221230-18:03:43    end: 20221230-18:03:43  %progress: 100 %    size: 0 B 
    status: done            time: 0s        from: [f:empty_value]
    error: none         end-in: 0s      to:   [t:empty_value]
    task type: mv           #files: 2       dst:  /FBX24T/dl/vm1/vm12
------------------------------------------------------------------------------------------------------------------------
id: 291 start: 20221230-18:12:18    end: 20221230-18:12:18  %progress: 100 %    size: 0 B 
    status: done            time: 0s        from: /FBX24T/dl/vm1/vm11/delta-opensuze-ZN87.qcow2
    error: none         end-in: 0s      to:   [t:empty_value]
    task type: rm           #files: 0       dst:  [d:empty_value]
------------------------------------------------------------------------------------------------------------------------
id: 299 start: 20221230-18:29:55    end: 20221230-18:30:03  %progress: 100 %    size: 1001 MB
    status: done            time: 0s        from: /FBX24T/dl/vm1/vm12/delta-opensuze.tar.gz
    error: none         end-in: 0s      to:   delta-opensuze-ZN90.qcow2
    task type: extract      #files: 0       dst:  /FBX24T/dl/vm1/vm13
------------------------------------------------------------------------------------------------------------------------
id: 303 start: 20221231-02:43:01    end: 20221231-02:43:44  %progress: 100 %    size: 9536 MB
    status: done            time: 38s       from: [f:empty_value]
    error: none         end-in: 0s      to:   [t:empty_value]
    task type: hash         #files: 1       dst:  [d:empty_value]
------------------------------------------------------------------------------------------------------------------------
id: 305 start: 20221231-10:27:48    end: 20221231-11:21:11  %progress: 100 %    size: 46 GB
    status: done            time: 3203s     from: /FBX24T/dl/delta-10G-xvxNX.tar.gz
    error: none         end-in: 0s      to:   /FBX24T/dl/vm1/vm15/nba50g.tar.gz
    task type: archive      #files: 1       dst:  /FBX24T/dl/delta-10G-xvxNX.tar.gz
------------------------------------------------------------------------------------------------------------------------
id: 329 start: 20230104-11:25:12    end: 20230104-11:31:59  %progress: 100 %    size: 500 MB
    status: done            time: 407s      from: /FBX24T/dl/vm1/vm13/delta-opensuze-ZN89.qcow2
    error: none         end-in: 0s      to:   /FBX24T/dl/vm1/vm13/nba500m1.7z
    task type: archive      #files: 2       dst:  /FBX24T/dl/vm1/vm13/delta-opensuze-ZN89.qcow2
------------------------------------------------------------------------------------------------------------------------
id: 285 start: 20221230-17:41:39    end: 20221230-17:41:39  %progress: 100 %    size: 0 B 
    status: failed          time: 0s        from: /FBX24T/dl/vm1/delta-10G-01.tar.gz
    error: dest_is_not_dir      end-in: 0s      to:   [t:empty_value]
    task type: cp           #files: 2       dst:  /FBX24T/dl/vm1/vm10
------------------------------------------------------------------------------------------------------------------------
id: 301 start: 20221231-02:41:29    end: 20221231-02:41:29  %progress: 100 %    size: 0 B 
    status: failed          time: 0s        from: /FBX24T/dl/delta-10G.tar.gz
    error: file_not_found       end-in: 0s      to:   [t:empty_value]
    task type: hash         #files: 0       dst:  [d:empty_value]
------------------------------------------------------------------------------------------------------------------------
Picture

fst_l

show_fs_task integer*

This function will simply show a particular filesystem tasks and also display its status This function have a pretty human readable outpout

Example
show_fs_task 329
                    SHOW FILESYSTEM TASK: 329

------------------------------------------------------------------------------------------------------------------------
id: 329 start: 20230104-11:25:12    end: 20230104-11:31:59  %progress: 100 %    size: 500 MB
    status: done            time: 407s      from: /FBX24T/dl/vm1/vm13/delta-opensuze-ZN89.qcow2
    error: none         end-in: 0s      to:   /FBX24T/dl/vm1/vm13/nba500m1.7z
    task type: archive      #files: 1       dst:  /FBX24T/dl/vm1/vm13/delta-opensuze-ZN89.qcow2
------------------------------------------------------------------------------------------------------------------------
Picture

fst_s

get_fs_task integer*

This function will simply retrieve informations on a particular filesystem tasks It provide a "machine' output to be parsed by another script or program

Example
get_fs_task 329

operation completed: 
{"success":true}

result:
{"curr_bytes_done":525300000,"total_bytes":525300000,"nfiles_done":1,"started_ts":1672827912,"duration":407,"done_ts":1672828319,"src":["/FBX24T/dl/vm1/vm13/nba500m1.7z"],"curr_bytes":525300000,"type":"archive","to":"/FBX24T/dl/vm1/vm13/nba500m1.7z","id":329,"nfiles":1,"created_ts":1672827912,"state":"done","total_bytes_done":525300000,"rate":0,"from":"/FBX24T/dl/vm1/vm13/delta-opensuze-ZN89.qcow2","dst":"/FBX24T/dl/vm1/vm13/delta-opensuze-ZN89.qcow2","eta":0,"error":"none","progress":100}
Picture

fst_g

hash_fs_task integer*

This function will simply retrieve the hash value of a file after it had been compute by a filesystem hash action task. When task is finished, this function show the hash value
This function provide a result only on 'hash' filesystem operation task

Example
hash_fs_task 303

operation completed: 
{"success":true}

result:
"0dad41fca4a5309b0a838d9928718a10ef6e08a51412753fe7ad41d9cd7b136625d8b083462f07ab9f8e9ce1a7ec30edb4a0eb730d01191df79588407b38238b"}
Picture

fst_h

upd_fs_task integer string*

This function will update a filesystem task. Possible updates actions: 'pause' or 'running' This function allow you to stop a task and to restart it later

Example
upd_fs_task 

ERROR: <param> for "upd_fs_task" must be some of:
id          # Task id: MUST be a number
state=          # Status action: paused or running 

NOTE: minimum parameters to specify on cmdline to update a download task: 
id 
state= 

EXAMPLE:
upd_fs_task 215 state="paused" 

operation failed !
Picture

upd_fst_r

Now we will pause a running fs task and restart it

Example
upd_fs_task 347 state=paused

operation completed: 
{"success":true}

result:
{"curr_bytes_done":97510000,"total_bytes":1050000000,"nfiles_done":0,"started_ts":1673618597,"duration":78,"done_ts":0,"src":["/FBX24T/dl/vm1/vm16/delta-osz.tar.xz","/FBX24T/dl/vm1/vm11/delta-opensuze-ZN89.qcow2"],"curr_bytes":525300000,"type":"archive","to":"/FBX24T/dl/vm1/vm16/delta-osz.tar.xz","id":347,"nfiles":2,"created_ts":1673618597,"state":"paused","total_bytes_done":97510000,"rate":0,"from":"/FBX24T/dl/vm1/vm11/delta-opensuze-ZN89.qcow2","dst":"/FBX24T/dl/vm1/vm11/delta-opensuze-ZN90.qcow2","eta":788,"error":"none","progress":9}
Picture

upd_fst_p

Let confirm the task is successfully updated and in status paused (see status value)

show_fs_task 347

                    SHOW FILESYSTEM TASK: 347

------------------------------------------------------------------------------------------------------------------------
id: 347 start: 20230113-15:03:17    end: 19700101-01:00:00  %progress: 9 %      size: 92 MB
    status: paused          time: 78s       from: /FBX24T/dl/vm1/vm11/delta-opensuze-ZN89.qcow2
    error: none         end-in: 788s        to:   /FBX24T/dl/vm1/vm16/delta-osz.tar.xz
    task type: archive      #files: 0       dst:  /FBX24T/dl/vm1/vm11/delta-opensuze-ZN90.qcow2
------------------------------------------------------------------------------------------------------------------------
Picture

upd_fst_ps

Now we will restart the task we just paused

Example
upd_fs_task 347 state=running

operation completed: 
{"success":true}

result:
{"curr_bytes_done":97510000,"total_bytes":1050000000,"nfiles_done":0,"started_ts":1673618597,"duration":78,"done_ts":0,"src":["/FBX24T/dl/vm1/vm16/delta-osz.tar.xz","/FBX24T/dl/vm1/vm11/delta-opensuze-ZN89.qcow2"],"curr_bytes":525300000,"type":"archive","to":"/FBX24T/dl/vm1/vm16/delta-osz.tar.xz","id":347,"nfiles":2,"created_ts":1673618597,"state":"running","total_bytes_done":97510000,"rate":0,"from":"/FBX24T/dl/vm1/vm11/delta-opensuze-ZN89.qcow2","dst":"/FBX24T/dl/vm1/vm11/delta-opensuze-ZN90.qcow2","eta":788,"error":"none","progress":9}
Picture

upd_fst_ru

Let confirm again the task is successfully updated and in status running (see status value)

show_fs_task 347

                    SHOW FILESYSTEM TASK: 347

------------------------------------------------------------------------------------------------------------------------
id: 347 start: 20230113-15:03:17    end: 19700101-01:00:00  %progress: 9 %      size: 92 MB
    status: running         time: 85s       from: /FBX24T/dl/vm1/vm11/delta-opensuze-ZN89.qcow2
    error: none         end-in: 781s        to:   /FBX24T/dl/vm1/vm16/delta-osz.tar.xz
    task type: archive      #files: 0       dst:  /FBX24T/dl/vm1/vm11/delta-opensuze-ZN90.qcow2
------------------------------------------------------------------------------------------------------------------------
Picture

upd_fst_rus

mon_fs_task integer*

This function monitor a filesystem task. When task are long (sometimes hours or days), and longer than the login session timeout the monitor function should logically be disconnected, so to avoid this behaviour, this function has the capacity of automatically relogin and continue monitoring. In other words, this function monitor the task in foreground and the login session in background and if session expire, it automatically relogin

Example
mon_fs_task 

ERROR: <param> must be :
id

NOTE: you can get a list of filesystem tasks (showing all 'id'), just run: 
list_fs_task_api

EXAMPLE:
mon_fs_task 215
Picture

mon_fst_r

Now we will monitor a running task

Example
mon_fs_task 348

task 348 running ... 
|.................................................                                                                 |  43 % 371s end: 480s 437MB
Picture

mon_fst_run2

And when the task is finished

Example
mon_fs_task 347
task 347 running ... 
|..................................................................................................................| 100 % 822s end: 0s 1001MB  
task 347 done ...
Picture

mon_fst_done

del_fs_task integer*

This function delete a filesystem task

Example
del_fs_task 

ERROR: <param> must be :
id

NOTE: you can get a list of filesystem tasks (showing all 'id'), just run: 
list_fs_task_api

EXAMPLE:
del_fs_task 215
Picture

del_fst_r

Now, we will delete our finished task 347

del_fs_task 347 

operation completed: 
{"success":true}
Picture

del_fst

And again, we will verify that our task had been successfully deleted with function 'show_fs_task'

show_fs_task 347 

                    SHOW FILESYSTEM TASK: 347

------------------------------------------------------------------------------------------------------------------------

No filesystem tasks to list !
Picture

del_fst_s

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

FILESYSTEM OPERATIONS (ACTIONS)

check_and_feed_fs_param array_of_strings*

This function will check if the provided arguments are valid parameters for the function which is calling it depending of the "action" set by the calling function. If not, function param_fs_err will be called to set error and display help for the command depending on "action" set by the calling function. "action" are: 'hash, extract, archive, mkdir, rename, cp, mv, rm, del'. This function will also check argument validity and return 0 if success or 1 if error. This function return a json 'fs_param_object' to be passed to the API call functions

Example
action=hash
check_and_feed_fs_param src="https://github.com/nbanb/fbx-delta-nba_bash_api.sh/raw/nbanb-freebox-api/FBXDSK/vm/vm1-disk0.qcow2" hash_type="sha256"
echo $fs_param_object
{"src":"L0ZCWERTSy92bS92bTEtZGlzazAucWNvdzI=","hash_type":"sha256"}

* param_fs_err

This function will display help / manual and example on the command which calling it, depending of the "action" set by the calling function. This function also set variable "error=1". "error" variable content is always checked before each API execution, and if error=1, nothing happends and the lib exit cleanly. "action" are: 'hash, extract, archive, mkdir, rename, cp, mv, rm, del'. This function return error=1 when it has been called This function is mostly called by 'check_and_feed_fs_param' function

ls_fs path optional_options*

This function list your box storage. To avoid performance issue when directory listing is big (which want to say that the json object replied by the API will be more than 100KB), this function CACHE result and work in-memory instead of polling the API each time we need to retrieve a value for each file (traditional way) Imagine if we need to retrieve 10 values on 100 files with no caching of results, we will need 1000 API call to print the result... Previous listing function of this library (list_fs_file) does not cache API results and suffers of performance issue when the directory contains more than 15 files or directories, so you MUST NOT use it except on very small directory, so with the new 'ms_fs' function, this old function become deprecated

Example
ls_fs /FBX24T/dl/vm1
idx: 0  hidden  dir 20230113-17:09:12   size: 4096 B    name: .
idx: 1  hidden  dir 20230112-09:33:26   size: 4096 B    name: ..
idx: 2      dir 20221230-17:59:09   size: 4096 B    name: vm10
idx: 3      dir 20221230-18:14:44   size: 4096 B    name: vm11
idx: 4      dir 20221230-18:23:33   size: 4096 B    name: vm12
idx: 5      dir 20230104-11:25:12   size: 4096 B    name: vm13
idx: 6      dir 20230103-22:17:21   size: 4096 B    name: vm14
idx: 7      dir 20221231-11:38:45   size: 4096 B    name: vm15
idx: 8      dir 20230113-15:37:38   size: 4096 B    name: vm16
idx: 9      dir 20230113-17:17:28   size: 4096 B    name: vm17
idx: 10     file    20221229-23:51:20   size: 9 GB  name: delta-10G-01.tar.gz
idx: 11     file    20221231-10:11:15   size: 9 GB  name: delta-10G-222.tar.gz
idx: 12     file    20221231-10:32:54   size: 9 GB  name: delta-10G-223.tar.gz
idx: 13     file    20221231-11:04:36   size: 9 GB  name: delta-10G-224.tar.gz
idx: 14     file    20221231-11:33:45   size: 9 GB  name: delta-10G-225.tar.gz
idx: 15     file    20221228-13:08:13   size: 500 MB    name: delta-opensuze-N87.qcow2
Picture

ls

This function also takes some optionals arguments to pass on the cmdline to filter output:

onlyFolder (bool)   --> Only list folders
removeHidden (bool) --> Don’t return hidden files in directory listing

These options are boolean so you must specify the value you affected to the option (0 or 1)

Example
ls_fs /FBX24T/dl/vm1 onlyFolder=1 removeHidden=0
idx: 0  hidden  dir 20230113-17:09:12   size: 4096 B    name: .
idx: 1  hidden  dir 20230112-09:33:26   size: 4096 B    name: ..
idx: 2      dir 20221230-17:59:09   size: 4096 B    name: vm10
idx: 3      dir 20221230-18:14:44   size: 4096 B    name: vm11
idx: 4      dir 20221230-18:23:33   size: 4096 B    name: vm12
idx: 5      dir 20230104-11:25:12   size: 4096 B    name: vm13
idx: 6      dir 20230103-22:17:21   size: 4096 B    name: vm14
idx: 7      dir 20221231-11:38:45   size: 4096 B    name: vm15
idx: 8      dir 20230113-15:37:38   size: 4096 B    name: vm16
idx: 9      dir 20230113-17:17:28   size: 4096 B    name: vm17
Picture

ls_opt

list_fs_file path*

$${\color{red}\text{This function is DEPRECATED and MUST NOT BE USED ! }}$$

This function intend to have the same function as 'ls_fs' function BUT

$${\color{red}\text{I let it in the lib as an example of what you should not do }}$$

cp_fs_file array_of_strings*

This function copy files provided as source files to the destination you provide as dst. This function act like 'cp' function in your bash terminal but only work on your box filesystem All copy operation will be enqueued as a filesystem task

Some copy operations an result in conflict, so you have to specify the conflict resolution mode on the cmdline when you copy some files.

Possible conflict resolution modes :
overwrite   --> Overwrite the destination file
both        --> Keep both files (rename the file adding a suffix)
recent      --> Only overwrite if newer than destination file
skip        --> Keep the destination file
Example
cp_fs_file

ERROR: <param> for "cp_fs_file" must be some of:
files=          # List of files to cp separated by a coma "," - avoid spaces in filename 
dst=            # The destination
mode=           # Conflict resolution : overwrite, both, skip, recent  

NOTE: minimum parameters to specify on cmdline to cp a file/dir: 
files=
dst=
mode= 

EXAMPLE (simple):
cp_fs_file files="/FBXDSK/vm/vm1-disk0.qcow2" dst="/FBXDSK/vm2" mode="overwrite" 

EXAMPLE (multiple files/dir):
cp_fs_file files="/FBXDSK/vm/vm1-disk0.qcow2,/FBXDSK/vm/vm2-disk0.qcow2" dst="/FBXDSK/vm2" mode="overwrite"
Picture

cp_r

Example
cp_fs_file files=/FBX24T/dl/vm1/delta-10G-222.tar.gz,/FBX24T/dl/vm1/delta-10G-223.tar.gz dst=/FBX24T/dl/vm1/vm17 mode=recent 


operation completed: 
{"success":true}

result:
{"curr_bytes_done":0,"total_bytes":0,"nfiles_done":0,"started_ts":1673626613,"duration":0,"done_ts":0,"src":["/FBX24T/dl/vm1/delta-10G-222.tar.gz","/FBX24T/dl/vm1/delta-10G-223.tar.gz"],"curr_bytes":0,"type":"cp","to":"","id":349,"nfiles":0,"created_ts":1673626613,"state":"running","total_bytes_done":0,"rate":0,"from":"","dst":"/FBX24T/dl/vm1/vm17","eta":0,"error":"none","progress":0}
Picture

cp

And now we will verify that our files had been successfully copied to the target directory (here /FBX24T/dl/vm1/vm17) with 'ls_fs' function

ls_fs /FBX24T/dl/vm1/vm17 
idx: 0  hidden  dir 20230113-17:17:28   size: 4096 B    name: .
idx: 1  hidden  dir 20230113-17:09:12   size: 4096 B    name: ..
idx: 2      file    20230113-17:17:28   size: 9 GB  name: delta-10G-222.tar.gz
idx: 3      file    20230113-17:18:03   size: 9 GB  name: delta-10G-223.tar.gz
Picture

cp_ok

mv_fs_file array_of_strings*

This function move provided files to the specified destination This function act like 'mv' function in your bash terminal but only work on your box filesystem All move operation will be enqueued as a filesystem task

Some move operations result in conflict, so you have to specify the conflict resolution mode on the cmdline when you move some files.

Possible conflict resolution modes :
overwrite   --> Overwrite the destination file
both        --> Keep both files (rename the file adding a suffix)
recent      --> Only overwrite if newer than destination file
skip        --> Keep the destination file
Example
mv_fs_file

ERROR: <param> for "mv_fs_file" must be some of:
files=          # List of files to mv separated by a coma "," - avoid spaces in filename 
dst=            # The destination
mode=           # Conflict resolution : overwrite, both, skip, recent  

NOTE: minimum parameters to specify on cmdline to mv a file/dir: 
files=
dst=
mode= 

EXAMPLE (simple):
mv_fs_file files="/FBXDSK/vm/vm1-disk0.qcow2" dst="/FBXDSK/vm2" mode="overwrite" 

EXAMPLE (multiple files/dir):
mv_fs_file files="/FBXDSK/vm/vm1-disk0.qcow2,/FBXDSK/vm/vm2-disk0.qcow2" dst="/FBXDSK/vm2" mode="overwrite"
Picture

mv_fst_r

If you forgot to specify the conflict 'mode' resolution, you will get the following error from API

Example
mv_fs_file files=/FBX24T/dl/vm1/delta-10G-222.tar.gz,/FBX24T/dl/vm1/delta-10G-223.tar.gz dst=/FBX24T/dl/vm1/vm18

operation failed ! 
Erreur lors du déplacement des fichiers : Le mode de résolution de conflit spécifié est invalide: invalid_conflict_mode
Picture

mv_fst_e

So, now we will specify the resolution mode

Example
mv_fs_file files=/FBX24T/dl/vm1/delta-10G-222.tar.gz,/FBX24T/dl/vm1/delta-10G-223.tar.gz dst=/FBX24T/dl/vm1/vm18 mode=overwrite

operation completed: 
{"success":true}

result:
{"curr_bytes_done":0,"total_bytes":0,"nfiles_done":0,"started_ts":1673686783,"duration":0,"done_ts":0,"src":["/FBX24T/dl/vm1/delta-10G-222.tar.gz","/FBX24T/dl/vm1/delta-10G-223.tar.gz"],"curr_bytes":0,"type":"mv","to":"","id":350,"nfiles":0,"created_ts":1673686783,"state":"running","total_bytes_done":0,"rate":0,"from":"","dst":"/FBX24T/dl/vm1/vm18","eta":0,"error":"none","progress":0}
Picture

mv_fst

Let's verify that our created task is sucessfully done with 'show_fs_task' function

Example
show_fs_task 350

                    SHOW FILESYSTEM TASK: 350

------------------------------------------------------------------------------------------------------------------------
id: 350 start: 20230114-09:59:43    end: 20230114-09:59:43  %progress: 100 %    size: 0 B 
    status: done            time: 0s        from: [f:empty_value]
    error: none         end-in: 0s      to:   [t:empty_value]
    task type: mv           #files: 0       dst:  /FBX24T/dl/vm1/vm18
------------------------------------------------------------------------------------------------------------------------
Picture

mv_fst_vs

Task is sucessfully done, so we will verify that files were successfully moved in the target directory with 'ls_fs' function

Example
ls_fs /FBX24T/dl/vm1/vm18
idx: 0  hidden  dir 20230114-09:59:43   size: 4096 B    name: .
idx: 1  hidden  dir 20230114-09:59:43   size: 4096 B    name: ..
idx: 2      file    20221231-10:11:15   size: 9 GB  name: delta-10G-222.tar.gz
idx: 3      file    20221231-10:32:54   size: 9 GB  name: delta-10G-223.tar.gz
Picture

mv_fst_vl

Files were moved, we can now delete the moving task (here #350) which had beed created for this example

del_fs_task 350

operation completed: 
{"success":true}
Picture

mv_fst_del

mkdir_fs_file array_of_strings*

This function is used to create directories on your box storage Contrary to other file system tasks, this operation is done synchronously.

Instead of a returning a Filessystem Task a call to this API will only return success status

Example
mkdir_fs_file

ERROR: <param> for "mkdir_fs_file" must be some of:
parent=         # The parent directory path 
dirname=        # The name of the directory to create 

NOTE: minimum parameters to specify on cmdline to create a directory: 
parent=
dirname= 

EXAMPLE:
mkdir_fs_file parent="/FBXDSK/vm" dirname="MyNewVMdir"
Picture

mkd_fs_r

Example
mkdir_fs_file parent=/FBX24T/dl/vm1 dirname=vm18

operation completed: 
{"success":true}

result:
"L0ZCWDI0VC9kbC92bTEvdm0xOA=="}
Picture

mkd_fs

The result return the base64 final directory path It can be verified from your bash terminal

Example
echo 'L0ZCWDI0VC9kbC92bTEvdm0xOA==' |base64 -d && echo
/FBX24T/dl/vm1/vm18
Picture

mkd_fs_vb

We can also verify that the directory had been successfully created using 'ls_fs' function: Just constat that our 'vm18' directory is present in path '/FBX24T/dl/vm1/'

Example
ls_fs /FBX24T/dl/vm1/
idx: 0  hidden  dir 20230114-09:59:43   size: 4096 B    name: .
idx: 1  hidden  dir 20230112-09:33:26   size: 4096 B    name: ..
idx: 2      dir 20221230-17:59:09   size: 4096 B    name: vm10
idx: 3      dir 20221230-18:14:44   size: 4096 B    name: vm11
idx: 4      dir 20221230-18:23:33   size: 4096 B    name: vm12
idx: 5      dir 20230104-11:25:12   size: 4096 B    name: vm13
idx: 6      dir 20230103-22:17:21   size: 4096 B    name: vm14
idx: 7      dir 20221231-11:38:45   size: 4096 B    name: vm15
idx: 8      dir 20230113-15:37:38   size: 4096 B    name: vm16
idx: 9      dir 20230113-17:17:28   size: 4096 B    name: vm17
idx: 10     dir 20230114-09:59:43   size: 4096 B    name: vm18
idx: 11     file    20221229-23:51:20   size: 9 GB  name: delta-10G-01.tar.gz
idx: 12     file    20221231-11:04:36   size: 9 GB  name: delta-10G-224.tar.gz
idx: 13     file    20221231-11:33:45   size: 9 GB  name: delta-10G-225.tar.gz
idx: 14     file    20221228-13:08:13   size: 500 MB    name: delta-opensuze-N87.qcow2
Picture

mkd_fs_vl

rename_fs_file array_of_strings*

This function is used to rename files and directories on your box storage Contrary to other file system tasks except 'mkdir_fs_file', this operation is done synchronously.

Instead of a returning a Filessystem Task a call to this API will only return success status

WARNING: The dst argument MUST ONLY CONTAIN new filename and NOT the whole path

Example
rename_fs_file

ERROR: <param> for "rename_fs_file" must be some of:
src=            # The source file path 
dst=            # The new name of the file (filename only, no path) 

NOTE: minimum parameters to specify on cmdline to  rename a file/dir: 
src=
dst= 

EXAMPLE:
rename_fs_file src="https://github.com/nbanb/fbx-delta-nba_bash_api.sh/raw/nbanb-freebox-api/FBXDSK/vm/vm1-disk0.qcow2" dst="vm2-disk2.qcow2"
Picture

ren_fs_r

Example
rename_fs_file src=/FBX24T/dl/vm1/vm18/delta-10G-222.tar.gz dst=delta-10G-222.tar.gz_renamed

operation completed: 
{"success":true}

result:
"L0ZCWDI0VC9kbC92bTEvdm0xOC9kZWx0YS0xMEctMjIyLnRhci5nel9yZW5hbWVk"}
Picture

ren

The result return the base64 final directory path It can be verified from your bash terminal

Example
echo 'L0ZCWDI0VC9kbC92bTEvdm0xOC9kZWx0YS0xMEctMjIyLnRhci5nel9yZW5hbWVk' |base64 -d && echo
/FBX24T/dl/vm1/vm18/delta-10G-222.tar.gz_renamed
Picture

ren_vb

Again, we can also verify that the file had been successfully renamed using 'ls_fs' function: Just constat that file delta-10G-222.tar.gz had been renamed to delta-10G-222.tar.gz_renamed

Example
ls_fs /FBX24T/dl/vm1/vm18
idx: 0  hidden  dir 20230114-10:55:54   size: 4096 B    name: .
idx: 1  hidden  dir 20230114-09:59:43   size: 4096 B    name: ..
idx: 2      file    20221231-10:11:15   size: 9 GB  name: delta-10G-222.tar.gz_renamed
idx: 3      file    20221231-10:32:54   size: 9 GB  name: delta-10G-223.tar.gz
Picture

ren_vl

rm_fs_file array_of_strings*

This function simply delete files or folders you passed as argument It act like your bash builtin command 'rm' but recursive and force options behaviour like 'rm -rf' is also applied here.

Example
rm_fs_file

ERROR: <param> for "rm_fs_file" must be some of:
files=          # List of files to rm separated by a coma "," - avoid spaces in filename 

NOTE: minimum parameters to specify on cmdline to  rm a file/dir: 
files= 

EXAMPLE (simple):
rm_fs_file files="/FBXDSK/vm/oldvm1-disk0.qcow2" 

EXAMPLE (multiple files/dir):
rm_fs_file files="/FBXDSK/vm/oldvm1-disk0.qcow2,/FBXDSK/vm/oldvm2-disk0.qcow2,/FBXDSK/vm/oldvm3-disk0.qcow2"
Picture

rm_fs_r

Example
rm_fs_file files=/FBX24T/dl/vm1/vm18/delta-10G-223.tar.gz,/FBX24T/dl/vm1/vm18/delta-10G-222.tar.gz_renamed

operation completed: 
{"success":true}

result:
{"curr_bytes_done":0,"total_bytes":0,"nfiles_done":0,"started_ts":1673710920,"duration":0,"done_ts":0,"src":["/FBX24T/dl/vm1/vm18/delta-10G-223.tar.gz","/FBX24T/dl/vm1/vm18/delta-10G-222.tar.gz_renamed"],"curr_bytes":0,"type":"rm","to":"","id":351,"nfiles":0,"created_ts":1673710920,"state":"running","total_bytes_done":0,"rate":0,"from":"/FBX24T/dl/vm1/vm18/delta-10G-223.tar.gz","dst":"","eta":0,"error":"none","progress":0}
Picture

rm_fs

Now we will verify that our files had been successfully been deleted with function 'ls_fs'

Example
ls_fs /FBX24T/dl/vm1/vm18
idx: 0  hidden  dir 20230114-16:42:01   size: 4096 B    name: .
idx: 1  hidden  dir 20230114-09:59:43   size: 4096 B    name: ..
Picture

rm_fs_vl

del_fs_file array_of_strings*

This function is an alias of the 'rm_fs_file' function. The only work of this function is to call 'rm_fs_file' and to pass it all its arguments So it takes the same parameters and syntaxe and provide the same output

See 'rm_fs_file' for detailed help and informations

hash_fs_file array_of_strings*

This function let you get compute the hash checksum value of a file. A task is created, enqueued and executed. When the task is finished and in status done, you must use 'hash_fs_task' function to retrieve the hash value, as describes in 'hash_fs_task' section of this README Supported hash format are :

md5     --> make a 'mdsum' on the target file
sha1        --> make a 'sha1sum' on the target file
sha256      --> make a 'sha256sum' on the target file
sha512      --> make a 'sha512sum' on the target file
Example
hash_fs_file

ERROR: <param> for "hash_fs_file" must be some of:
src=                # The source file path to hash 
hash_type=          # The hash algo, can be: md5 sha1 sha256 sha512  

NOTE: minimum parameters to specify on cmdline to  hash a file/dir: 
src=
hash_type= 

EXAMPLE:
hash_fs_file src="https://github.com/nbanb/fbx-delta-nba_bash_api.sh/raw/nbanb-freebox-api/FBXDSK/vm/vm1-disk0.qcow2" hash_type="sha256"
Picture

h_r

Now we will hash a file

Example
hash_fs_file src=/FBX24T/dl/vm1/vm18/delta-10G-225.tar.gz hash_type=sha512

operation completed: 
{"success":true}

result:
{"curr_bytes_done":0,"total_bytes":0,"nfiles_done":0,"started_ts":1673712615,"duration":0,"done_ts":0,"curr_bytes":0,"type":"hash","to":"","id":355,"nfiles":0,"created_ts":1673712615,"state":"running","total_bytes_done":0,"rate":0,"from":"","dst":"","eta":0,"error":"none","progress":0}
Picture

h_512

So, let's monitor our hash task

Example
mon_fs_task_api 355

Waiting for the end of the task 

task 355 running ... 
|..................................................................................................................| 100 % 43s end: 0s 9536MB  
task 355 done ...
Picture

Running h_mon Finished h_mon_e

And verifying the task is in status 'done' with "show_fs_task" function

show_fs_task_api 355

                    SHOW FILESYSTEM TASK: 355

------------------------------------------------------------------------------------------------------------------------
id: 355 start: 20230114-17:10:15    end: 20230114-17:10:58  %progress: 100 %    size: 9536 MB
    status: done            time: 43s       from: [f:empty_value]
    error: none         end-in: 0s      to:   [t:empty_value]
    task type: hash         #files: 0       dst:  [d:empty_value]
------------------------------------------------------------------------------------------------------------------------
Picture

h_tsk

To finished, we will now retrieve our hash value with function 'hash_fs_task'

Example
hash_fs_task 355

operation completed: 
{"success":true}

result:
"0dad41fca4a5309b0a838d9928718a10ef6e08a51412753fe7ad41d9cd7b136625d8b083462f07ab9f8e9ce1a7ec30edb4a0eb730d01191df79588407b38238b"}
Picture

h_val

archive_fs_file array_of_strings*

This function will make an archive with the files provided as argument. Supported archive type:

.zip        --> a 'zip' archive will be created
.iso        --> a 'iso' archive will be created
.cpio       --> a 'cpio' archive will be created
.tar        --> a 'tar' archive will be created
.tar.gz     --> a 'tar' archive will be created compressed with 'gzip'
.tar.xz     --> a 'tar' archive will be created compressed with 'lzma'
.7z     --> a '7zip' archive will be created
.tar.7z     --> a 'tar' archive will be created compressed with '7zip'
.tar.bz2    --> a 'tar' archive will be created compressed with 'bzip2'

The archive type is autodetected by the API from the target archive filename extension If you named your archive 'someting.zip', a zip archive will be done If you named your archive 'someting.tar', a tar archive will be done ...

Example
archive_fs_file

ERROR: <param> for "archive_fs_file" must be some of:
files=          # List of files fullpath separated by a coma "," 
dst=            # The destination archive (name of the archive) 

NOTE: minimum parameters to specify on cmdline to create an archive: 
files=
dst= 

NOTE: archive type will be autodetect from archive filename extention - supported type: 
.zip
.iso
.cpio
.tar
.tar.gz
.tar.xz
.7z
.tar.7z
.tar.bz2 

EXAMPLE (simple):
archive_fs_file files="/FBXDSK/vm/vm1-disk0.qcow2" dst="/FBXDSK/vm/archive.zip" 

EXAMPLE (multiple files/dir):
archive_fs_file files="/FBXDSK/vm/vm1-disk0.qcow2,/FBXDSK/vm/vm2-disk0.qcow2" dst="/FBXDSK/vm/archive.zip"
Picture

arc_r

Example
archive_fs_file files=/FBX24T/dl/vm1/vm18/mjd-efi-arm64.qcow2,/FBX24T/dl/vm1/vm18/njd-efi-arm64.qcow2 dst=/FBX24T/dl/vm1/vm18/jd-efi-arm64.qcow2.tar

operation completed: 
{"success":true}

result:
{"curr_bytes_done":0,"total_bytes":0,"nfiles_done":0,"started_ts":1673715829,"duration":0,"done_ts":0,"src":["/FBX24T/dl/vm1/vm18/jd-efi-arm64.qcow2.tar","/FBX24T/dl/vm1/vm18/mjd-efi-arm64.qcow2"],"curr_bytes":0,"type":"archive","to":"/FBX24T/dl/vm1/vm18/jd-efi-arm64.qcow2.tar","id":358,"nfiles":0,"created_ts":1673715829,"state":"running","total_bytes_done":0,"rate":0,"from":"","dst":"/FBX24T/dl/vm1/vm18/njd-efi-arm64.qcow2","eta":0,"error":"none","progress":0}
Picture

arc

Again, let monitor our archive task

Example
mon_fs_task_api 358
task 358 running ... 
|..................................................................................................................| 100 % 24s end: 0s 5998MB  
task 358 done ...
Picture

a_mon

And confirm our archive task is finished with 'show_fs_task' function

show_fs_task 358
                    SHOW FILESYSTEM TASK: 358

------------------------------------------------------------------------------------------------------------------------
id: 358 start: 20230114-18:03:49    end: 20230114-18:04:14  %progress: 100 %    size: 5998 MB
    status: done            time: 24s       from: /FBX24T/dl/vm1/vm18/njd-efi-arm64.qcow2
    error: none         end-in: 0s      to:   /FBX24T/dl/vm1/vm18/jd-efi-arm64.qcow2.tar
    task type: archive      #files: 2       dst:  /FBX24T/dl/vm1/vm18/njd-efi-arm64.qcow2
------------------------------------------------------------------------------------------------------------------------
Picture

a_s

When the task is finished, it can be delete with 'del_fs_task' function Let verify that our archive had been sucessfully created with 'ls_fs' function

ls_fs /FBX24T/dl/vm1/vm18
idx: 0  hidden  dir 20230114-18:03:49   size: 4096 B    name: .
idx: 1  hidden  dir 20230114-09:59:43   size: 4096 B    name: ..
idx: 2      file    20230114-17:02:55   size: 9 GB  name: delta-10G-224.tar.gz
idx: 3      file    20230114-17:03:33   size: 9 GB  name: delta-10G-225.tar.gz
idx: 4      file    20230114-18:04:14   size: 5 GB  name: jd-efi-arm64.qcow2.tar
idx: 5      file    20230114-17:58:49   size: 2 GB  name: mjd-efi-arm64.qcow2
idx: 6      file    20230114-18:01:34   size: 2 GB  name: njd-efi-arm64.qcow2
Picture

a_l

extract_fs_file array_of_strings*

This function will extract an archive from the files provided as argument. Supported archive type:

.zip        --> 'zip' archive will be extracted with 'zip'
.iso        --> 'iso' archive will be extracted 
.cpio       --> 'cpio' archive will be extracted
.tar        --> 'tar' archive will be extracted with 'tape archiver'
.tar.gz     --> 'tar' archive will be extracted with 'gzip'
.tar.xz     --> 'tar' archive will be extracted with 'lzma'
.7z     --> '7zip' archive will be extracted with '7zip'
.tar.7z     --> 'tar' archive will be extracted with '7zip'
.tar.bz2    --> 'tar' archive will be extracted with 'bzip2'

The archive type is autodetected by the API from the archive filename extension If your archive is named 'someting.zip', zip will be used for extraction If your archive is named 'someting.tar', tar will be used for extraction ...

Note: If the provided archive has a password, you can specify the option 'password=' on the cmdline You can also specify the option 'delete_archive=1' on the cmdline to delete archive after extraction but you must also specify the conflict resoution mode with option 'overwrite=0 or overwrite=1' on the cmdline

Example
extract_fs_file

ERROR: <param> for "extract_fs_file" must be some of:
src=            # The archive file
dst=            # The destination folder 
password=       # (Optionnal) The archive password
delete_archive=     # boolean true or false (Optionnal) Delete archive after extraction 
overwrite=      # boolean true or false (Optionnal) Overwrite files on conflict

NOTE: minimum parameters to specify on cmdline to extract an archive: 
src=
dst= 

NOTE: archive type will be autodetect from archive filename extention - supported type: 
.zip
.iso
.cpio
.tar
.tar.gz
.tar.xz
.7z
.tar.7z
.tar.bz2 

EXAMPLE (simple):
extract_fs_file src="https://github.com/nbanb/fbx-delta-nba_bash_api.sh/raw/nbanb-freebox-api/FBXDSK/vm/archive.zip" dst="/FBXDSK/vm" 

EXAMPLE (medium):
extract_fs_file src="https://github.com/nbanb/fbx-delta-nba_bash_api.sh/raw/nbanb-freebox-api/FBXDSK/vm/archive.zip" dst="/FBXDSK/vm" password="MyArchivePassword" 

EXAMPLE (full):
extract_fs_file src="https://github.com/nbanb/fbx-delta-nba_bash_api.sh/raw/nbanb-freebox-api/FBXDSK/vm/archive.zip" dst="/FBXDSK/vm" password="MyArchivePassword" delete_archive="1" overwrite="0"
Picture

e_fs_r

Let extract the archive we had just created in previous documented function of this README 'archive_fs_file'

Example
extract_fs_file src=/FBX24T/dl/vm1/vm18/jd-efi-arm64.qcow2.tar dst=/FBX24T/dl/vm1/vm19 overwrite=1 

operation completed: 
{"success":true}

result:
{"curr_bytes_done":0,"total_bytes":0,"nfiles_done":0,"started_ts":1673854880,"duration":0,"done_ts":0,"src":["/FBX24T/dl/vm1/vm18/jd-efi-arm64.qcow2.tar"],"curr_bytes":0,"type":"extract","to":"/FBX24T/dl/vm1/vm19","id":364,"nfiles":0,"created_ts":1673854880,"state":"running","total_bytes_done":0,"rate":0,"from":"/FBX24T/dl/vm1/vm18/jd-efi-arm64.qcow2.tar","dst":"/FBX24T/dl/vm1/vm19","eta":0,"error":"none","progress":0}
Picture

e_fs

Again we will monitor our task until it finished

mon_fs_task_api 364
task 364 running ... 
|..................................................................................................................| 100 % 23s end: 0s 5998MB  
task 364 done ...
Picture

e_fs_m

And again, we will verify and constat with function 'ls_fs' that the archive had been successfully extracted to directory '/FBX24T/dl/vm1/vm19'

ls_fs /FBX24T/dl/vm1/vm19
idx: 0  hidden  dir 20230116-08:41:31   size: 4096 B    name: .
idx: 1  hidden  dir 20230116-08:26:25   size: 4096 B    name: ..
idx: 2      file    20230114-17:58:49   size: 2 GB  name: mjd-efi-arm64.qcow2
idx: 3      file    20230114-18:01:34   size: 2 GB  name: njd-efi-arm64.qcow2
Picture

e_fs_v

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API FRONTEND FUNCTIONS - VIRTUAL MACHINE

You must notice that today, as I had already wrote a 'nearly' complete program for managing Freebox Delta virtual Machines from bash with api and which is also using some of the LOGIN FUNCTIONS and of the CALL FUNCTIONS of this library (I wrote those function before writing the library new frontend functions), and at the time I was first writing, there were very few functions in this library for managing Freebox Delta Virtual Machines. The 'nearly' complete program to manage Freebox Delta virtual machines from API and bash can be find here: fbxvm-ctrl

Since the whole documentation had been written, the new Freebox ULTRA appears in 2024 and have also VM feature, so I decide to port directly in library all Virtual Machines functions (and more) that I did developp in my other program fbxvm-ctrl


Extended Virtual Machines support in library :
--> Now the following functions are usable directly from the library (= from the shell).
--> Documentation is not updated at the time I'm writing, but all functions include help and example

Note :
--> VNC usage over websocket required you install TigerVNC client: https://tigervnc.org/

New :
--> Function auto_relogin on all control VM function (vm_start, sm_stop, vm_console...)
--> Fixing websocket timeout while using vm_console or vm_vnc command

New VM functions supported : (adding vm display screen support)

function : description
$${\color{red}\text{Calling function with no parameters will print help }}$$
vm_vnc launch VM VNC screen through Websocket API - (Require option: enable_screen=true)
vm_svnc start VM and launch VNC screen just after starting VM


VM already supported function :

function : description
$${\color{red}\text{Calling function with no parameters will print help }}$$
vm_add add a new vm
vm_adddisk add a new disk for a VM
vm_console launch VM console (through Freebox Websocket API - it act as an Out-Of-Band access)
vm_deldisk remove a VM disk
vm_delete remove a VM
vm_detail print VM configuration detail and status
vm_list list all VM
vm_listdisk list all disks from a vmdisk directory
vm_modify modify VM parameters
vm_param print detailed help of ALL VM parameters
vm_reload execute an ACPI shutdown and after start the VM again
vm_resizedisk resize vM disk
vm_resource print allocated and used ressources - json output
vm_restart hard stop VM (electricaly) and after start the VM again
vm_sconsole start VM and launch console just after starting VM
vm_show list a specific VM
vm_shutdown send an ACPI shutdown command to the VM
vm_start simply start VM
vm_stop hard stop VM (electricaly)


TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API FRONTEND FUNCTIONS - VM PREBUILD DISTROS

This API let you list and download Freebox Delta Free's prebuild vm distros For this API, we only have 4 functions for listing and downloading Freebox Delta prebuild vm distros

As I'm never using prebuild VM images that someone other than me had installed, I didn't develop thoses functions in my previously written program fbxvm-ctrl. But as some of my program users asked me, I did develop these new frontend functions + downloads capabilities and others frontend functions of this library

So here, I'm only managing the part I did not developped in my other program fbxvm-ctrl That's why the lisiting and check_and_feed_vm__prebuild_distros function will publish some environnement variables containing distros parameters to subshell. This way, if you use fbxvm-ctrl program for managing VM, you can just list all prebuild VM distros from this library function, and after you can use the created environment variables to be passed as parameters to fbxvm-ctrl when creating a Virtual Machine or when updating a VM

check_and_feed_vm_prebuild_distros_param array_of_strings*

This function will check if the provided arguments are valid parameters for the function which is calling it depending of the "action" set by the calling function. If not, function param_vm_prebuild_distros_err will be called to set error and display help for the command depending on "action" set by the calling function. "action" are: 'dl' (=download). This function do not return a 'json' object to be passed to "API CALL" functions because it fulfill some session exported variables (bash arrays) containing the whole list of variables / values for all prebuild VM distros.

Example
action=dl
check_and_feed_vm_prebuild_distros_param id=5 dl_path=/FBXSTORAGE/VMdownload filename=myOpenSuzeVM-7.qcow2
echo -e "${distro_url[@]}"|tr " " "\n"
http://ftp.free.fr/.private/ubuntu-cloud/releases/jammy/release/ubuntu-22.04-server-cloudimg-arm64.img
http://ftp.free.fr/.private/ubuntu-cloud/releases/impish/release/ubuntu-21.10-server-cloudimg-arm64.img
https://cloud.debian.org/images/cloud/bullseye/daily/latest/debian-11-generic-arm64-daily.qcow2
https://cloud.debian.org/images/cloud/sid/daily/latest/debian-sid-generic-arm64-daily.qcow2
http://ftp.free.fr/pub/Distributions_Linux/Fedora/releases/36/Cloud/aarch64/images/Fedora-Cloud-Base-36-1.5.aarch64.qcow2
http://ftp.free.fr/mirrors/ftp.opensuse.org/opensuse/distribution/leap/15.4/appliances/openSUSE-Leap-15.4-ARM-JeOS-efi.aarch64.qcow2
https://cloud.centos.org/centos/8/aarch64/images/CentOS-8-GenericCloud-8.4.2105-20210603.0.aarch64.qcow2
https://images.jeedom.com/freebox/freeboxDelta.qcow2
echo -e "${distro_name[@]}" |tr " " "\n"
Ubuntu_22.04_LTS_(Jammy)     
Ubuntu_21.10_(Impish)    
Debian_11_(Bullseye)     
Debian_Unstable_(sid)    
Fedora_36            
openSUSE_Leap_15.4_JeOS  
CentOS_8.4_(snapshot_20210603) 
Jeedom_(fourni_par_Jeedom_SAS)
...
Picture

vm_d_c

* param_vm_prebuild_distros_err

This function will display help / manual and example on the command which calling it, depending of the "action" set by the calling function. This function also set variable "error=1". "error" variable content is always checked before each API execution, and if error=1, nothing happends and the lib exit cleanly. "action" are: 'add, upd, del, ena, dis'. This function return error=1 when it has been called This function is mostly called by 'check_and_feed_vm_prebuild_distros_param' function

* list_vm_prebuild_distros

This function list all availiable Virtual Machines (VM) prebuild distros. These are FREEBOX distros from from Free Telecom, not mine. I can also provide some prebuild distros with security enforcement, just ask... But use at your own risk As this function can automatically fulfill and export to subshell all variables and values of all Free VM prebuild distros, the list function can be used without providing output using the '-q' switch in the comand line

Example
list_vm_prebuild_distros -h

function param:
        -h  print this help
        -q  silently export distros variables - no output
Picture

vm_d_q

Example
list_vm_prebuild_distros -q

Now, you can retrieve distros information directly from environement variables. the following variables are exported : $distro_count --> number of availiabledistros $distro_filename --> array of all distros filenames $distro_hash --> array of all distros hash URL $distro_name --> array of all distro names $distro_os --> array of all distro os - to be pass when creating a VM $distro_url --> array of all distro URL $distro_idx --> array of all distro variables ($distro_filename,$distro_hash, ...)

Let see an example with a simple bash loop printing variables of some distros

i=3 
while [[ "$i" != "${#distro_name[@]}" ]]; 
do 
    echo -e "distro $i"
    echo -e "${distro_os[$i]}"
    echo -e "${distro_name[$i]}"
    echo -e "${distro_url[$i]}"
    echo -e "${distro_hash[$i]}"
    echo -e "${distro_filename[$i]}\n"
    ((i++))
done
distro 3
debian
Debian_Unstable_(sid)   
https://cloud.debian.org/images/cloud/sid/daily/latest/debian-sid-generic-arm64-daily.qcow2
https://cloud.debian.org/images/cloud/sid/daily/latest/SHA512SUMS
debian-sid-generic-arm64-daily.qcow2

distro 4
fedora
Fedora_36           
http://ftp.free.fr/pub/Distributions_Linux/Fedora/releases/36/Cloud/aarch64/images/Fedora-Cloud-Base-36-1.5.aarch64.qcow2
http://ftp.free.fr/pub/Distributions_Linux/Fedora/releases/36/Cloud/aarch64/images/Fedora-Cloud-36-1.5-aarch64-CHECKSUM
Fedora-Cloud-Base-36-1.5.aarch64.qcow2

distro 5
opensuse
openSUSE_Leap_15.4_JeOS 
http://ftp.free.fr/mirrors/ftp.opensuse.org/opensuse/distribution/leap/15.4/appliances/openSUSE-Leap-15.4-ARM-JeOS-efi.aarch64.qcow2
http://ftp.free.fr/mirrors/ftp.opensuse.org/opensuse/distribution/leap/15.4/appliances/openSUSE-Leap-15.4-ARM-JeOS-efi.aarch64.qcow2.sha256
openSUSE-Leap-15.4-ARM-JeOS-efi.aarch64.qcow2

distro 6
centos
CentOS_8.4_(snapshot_20210603)
https://cloud.centos.org/centos/8/aarch64/images/CentOS-8-GenericCloud-8.4.2105-20210603.0.aarch64.qcow2
[no_hashfile_url_available]
CentOS-8-GenericCloud-8.4.2105-20210603.0.aarch64.qcow2

distro 7
jeedom
Jeedom_(fourni_par_Jeedom_SAS)
https://images.jeedom.com/freebox/freeboxDelta.qcow2
https://images.jeedom.com/freebox/SHA256SUMS
freeboxDelta.qcow2
Picture

vm_d_var

Now we will use the 'list_vm_prebuild_distros' function with no argument to have it's normal output Note that distros variables will also be exported to subshell environment

Example
list_vm_prebuild_distros 

                LIST AVAILIABLE 'Freebox Delta' PREBUILD VM DISTROS IMAGES:

----------------------------------------------------------------------------------------------------------------------------------------------------------
id: 0   name=Ubuntu 22.04 LTS (Jammy)       os=ubuntu   filename=ubuntu-22.04-server-cloudimg-arm64.img
    url=http://ftp.free.fr/.private/ubuntu-cloud/releases/jammy/release/ubuntu-22.04-server-cloudimg-arm64.img
    hash=http://ftp.free.fr/.private/ubuntu-cloud/releases/jammy/release/SHA256SUMS
----------------------------------------------------------------------------------------------------------------------------------------------------------
id: 1   name=Ubuntu 21.10 (Impish)      os=ubuntu   filename=ubuntu-21.10-server-cloudimg-arm64.img
    url=http://ftp.free.fr/.private/ubuntu-cloud/releases/impish/release/ubuntu-21.10-server-cloudimg-arm64.img
    hash=http://ftp.free.fr/.private/ubuntu-cloud/releases/impish/release/SHA256SUMS
----------------------------------------------------------------------------------------------------------------------------------------------------------
id: 2   name=Debian 11 (Bullseye)       os=debian   filename=debian-11-generic-arm64-daily.qcow2
    url=https://cloud.debian.org/images/cloud/bullseye/daily/latest/debian-11-generic-arm64-daily.qcow2
    hash=https://cloud.debian.org/images/cloud/bullseye/daily/latest/SHA512SUMS
----------------------------------------------------------------------------------------------------------------------------------------------------------
id: 3   name=Debian Unstable (sid)      os=debian   filename=debian-sid-generic-arm64-daily.qcow2
    url=https://cloud.debian.org/images/cloud/sid/daily/latest/debian-sid-generic-arm64-daily.qcow2
    hash=https://cloud.debian.org/images/cloud/sid/daily/latest/SHA512SUMS
----------------------------------------------------------------------------------------------------------------------------------------------------------
id: 4   name=Fedora 36              os=fedora   filename=Fedora-Cloud-Base-36-1.5.aarch64.qcow2
    url=http://ftp.free.fr/pub/Distributions_Linux/Fedora/releases/36/Cloud/aarch64/images/Fedora-Cloud-Base-36-1.5.aarch64.qcow2
    hash=http://ftp.free.fr/pub/Distributions_Linux/Fedora/releases/36/Cloud/aarch64/images/Fedora-Cloud-36-1.5-aarch64-CHECKSUM
----------------------------------------------------------------------------------------------------------------------------------------------------------
id: 5   name=openSUSE Leap 15.4 JeOS        os=opensuse filename=openSUSE-Leap-15.4-ARM-JeOS-efi.aarch64.qcow2
    url=http://ftp.free.fr/mirrors/ftp.opensuse.org/opensuse/distribution/leap/15.4/appliances/openSUSE-Leap-15.4-ARM-JeOS-efi.aarch64.qcow2
    hash=http://ftp.free.fr/mirrors/ftp.opensuse.org/opensuse/distribution/leap/15.4/appliances/openSUSE-Leap-15.4-ARM-JeOS-efi.aarch64.qcow2.sha256
----------------------------------------------------------------------------------------------------------------------------------------------------------
id: 6   name=CentOS 8.4 (snapshot 20210603) os=centos   filename=CentOS-8-GenericCloud-8.4.2105-20210603.0.aarch64.qcow2
    url=https://cloud.centos.org/centos/8/aarch64/images/CentOS-8-GenericCloud-8.4.2105-20210603.0.aarch64.qcow2
    hash=[no_hashfile_url_available]
----------------------------------------------------------------------------------------------------------------------------------------------------------
id: 7   name=Jeedom (fourni par Jeedom SAS) os=jeedom   filename=freeboxDelta.qcow2
    url=https://images.jeedom.com/freebox/freeboxDelta.qcow2
    hash=https://images.jeedom.com/freebox/SHA256SUMS
----------------------------------------------------------------------------------------------------------------------------------------------------------
Picture

vm_d_l

* dl_vm_prebuild_distros

This function let you download one of the VM prebuild distros on the path of your choice and name the download image with the name you provided as parameter (or with it's original name if you don't specify it on the command lines arguments

Example
dl_vm_prebuild_distros

ERROR: <param> for "dl_vm_prebuild_distros" must be some of:
id=         # distro id for selected distro in distro list
dl_path=        # optional download path (override default download_dir - non existent directory will be created)
filename=       # optional filename (override default filename)

NOTE: please run "list_vm_prebuild_distros" to get list of all prebuild VM distros 

NOTE: minimum parameters to specify on cmdline to dowload a VM prebuild distro: 
id=

EXAMPLE: (simple)
dl_vm_prebuild_distros id=5

EXAMPLE: (full)
dl_vm_prebuild_distros id=5 dl_path=/FBXSTORAGE/VMdownload filename=myOpenSuzeVM-7.qcow2
Picture

dl_vmp_r

Example
dl_vm_prebuild_distros id=7 dl_path=/FBX24T/dl/vm6 filename=MyDeltaJeeDom.qcow2

operation completed: 
{"success":true}

result:
{"id":483}

task 483 downloading ... 
|..................................................................................................................| 100 % 0 MB/s 2994/2994MB 
task 483 checking ... 
|..................................................................................................................| 100 % checking ... 
task 483 done ... 

Download Task log: task 483

2023-01-13 09:04:02 info: start url https://images.jeedom.com/freebox/freeboxDelta.qcow2 (crawling: 1)
2023-01-13 09:04:02 dbg: host resolved to 51.210.253.116:443
2023-01-13 09:04:02 dbg: connecting to remote host...
2023-01-13 09:04:02 dbg: connected
2023-01-13 09:04:02 dbg: sending request headers:
2023-01-13 09:04:02 dbg:    User-Agent: Mozilla/5.0
2023-01-13 09:04:02 dbg:    Host: images.jeedom.com:443
2023-01-13 09:04:02 dbg: request headers sent
2023-01-13 09:04:02 dbg: got response headers:
2023-01-13 09:04:02 dbg:    Strict-Transport-Security: max-age=15724800; includeSubDomains
2023-01-13 09:04:02 dbg:    Last-Modified: Tue, 08 Oct 2019 01:10:03 GMT
2023-01-13 09:04:02 dbg:    ETag:bbe0000-5945bd3fc10c0
2023-01-13 09:04:02 dbg:    Date: Fri, 13 Jan 2023 08:04:02 GMT
2023-01-13 09:04:02 dbg:    Content-Length: 3149791232
2023-01-13 09:04:02 dbg:    Connection: keep-alive
2023-01-13 09:04:02 dbg:    Accept-Ranges: bytes
2023-01-13 09:04:02 info: unable to resume (missing content_range)
2023-01-13 09:04:02 dbg: receiving body

Sucessfully delete task #483: {"success":true}
Picture

Download progress dl_vmp_p

Download finished dl_vm_f

Now, we will verify that our prebuild VM distro image had been successfully downloaded in path '/FBX24T/dl/vm6' and have for filename 'MyDeltaJeeDom.qcow2' To proceed, we will use one of the frontend FILESYSTEM FUNCTIONS to list the content of freebox storage

Example
ls_fs /FBX24T/dl/vm6
idx: 0  hidden  dir 20230113-09:04:02   size: 4096 B    name: .
idx: 1  hidden  dir 20230112-09:33:26   size: 4096 B    name: ..
idx: 2      file    20230113-09:15:05   size: 2 GB  name: MyDeltaJeeDom.qcow2
Picture

dl_vm_ls

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API FRONTEND FUNCTIONS - REPLY OUTPUT

For managing output of all frontend function for a direct use from a bash terminal or for use inside other program / script, 2 functions had been developped and there are several possibility to keep the formatting output when filtering results (see filtering):

colorize_output string*

This function will print result in a colour and formated way, splitting result status and output messages:

Example
logout_freebox
answer=$(call_freebox_api /vm/info 2>&1)
colorize_output $answer

operation failed ! 
Vous devez vous connecter pour accéder à cette fonction: auth_required
Picture

c_o_f

Example
relogin_freebox 
answer=$(call_freebox_api /vm/info 2>&1)
colorize_output $answer

operation completed: 
{"success":true}

result:
{"usb_used":false,"sata_used":false,"sata_ports":["sata-internal-p0","sata-internal-p1","sata-internal-p2","sata-internal-p3"],"used_memory":8192,"usb_ports":["usb-external-type-a","usb-external-type-c"],"used_cpus":3,"total_memory":15360,"total_cpus":3}
Picture

c_o_o

colorize_output_pretty_json string*

This function will print result in a colour and formated way, splitting result status and output messages:

This function will also print JSON output in "pretty-json" manner. When you have the API reply with a big json reply, it's sometimes nearly impossible to read and understand it. Displaying those kind of json strings in "pretty-json" way let json output becoming human readable

Example
logout_freebox
answer=$(call_freebox_api /vm/info 2>&1)
colorize_output_pretty_json $answer

operation failed ! 
Vous devez vous connecter pour accéder à cette fonction: auth_required
Picture

c_o_pf

Example
relogin_freebox
answer=$(call_freebox_api /vm/info 2>&1)
colorize_output_pretty_json $answer

operation completed: 

 {
    "success":true
 }
 {
    "usb_used":false,
    "sata_used":false,
    "sata_ports":
    [
        "sata-internal-p0",
        "sata-internal-p1",
        "sata-internal-p2",
        "sata-internal-p3"
    ],
    "used_memory":8192,
    "usb_ports":
    [
        "usb-external-type-a",
        "usb-external-type-c"
    ],
    "used_cpus":3,
    "total_memory":15360,
    "total_cpus":3
 }
Picture

c_o_po

filtering output

To keep the formatting of the output of the frontend functions of the library when filtering output / results of a command or of a listing command, you can use several way to filter on a pattern and to keep the formatting

Example

Here we will list all dhcp static leases and filter on a particular mac address

Note that I'm using '--color=never' option of 'grep' because I want to keep the library formatting for the picture. You can replace this filtering expression (grep --color=never '00:01:02:03:04:05') by:

All of those 3 commands provide the same result and output, so you can use those 3 command in your scripts to retrieve a particular string without alterating the library output. (see the following example and picture)

Example

No alteration with grep 

list_dhcp_static_lease | grep --color=never '00:01:02:03:04:05'
6:      00:01:02:03:04:05       00:01:02:03:04:05       192.168.100.46          offline         00:01:02:03:04:05
Picture

ad_dh_g

Example

No alteration with awk

list_dhcp_static_lease | awk  '$2 ~ /00:01:02:03:04:05/'
6:      00:01:02:03:04:05       00:01:02:03:04:05       192.168.100.46          offline         00:01:02:03:04:05
Picture

ad_dh_a

Example

No alteration with sed

list_dhcp_static_lease | sed '/00:01:02:03:04:05/!d'
6:      00:01:02:03:04:05       00:01:02:03:04:05       192.168.100.46          offline         00:01:02:03:04:05
Picture

ad_dh_s

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

API DIRECT ACTIONS

* reboot_freebox

This function will reboot your freebox. Return code will be 0 if the freebox is rebooting, 1 otherwise. The application must be granted to modify the setup of the freebox (from freebox web interface, see: GRANT API ACCESS)

Example
reboot_freebox
TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

GRANT API ACCESS IN YOUR BOX OS (FreeboxOS, IliadboxOS)

mafbx

mafbx-param

See the following capture:

fbx-app-axx

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

PUBLIC URL - TLS CERTIFICATE - API REMOTE ACCESS

If you want to configure a WAN URL on a public domain, here are the prerequisite:

DOMAIN NAME

You need a public domain name to access your box from internet

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

TLS CERTIFICATE

You also need a TLS certificate configured for your new domain fbx.my-public-domain.net

Once you have your public URL pointing to your Freebox and a valid TLS certificate for it, go on FreeboxOS interface on https://mafreebox.freebox.fr or if you are in Italy on https://myiliadbox.iliadbox.it from your local network, login and proceed as describe on the following procedure

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

CONFIGURE REMOTE ACCESS

Login to your box OS:

mafbx

Access the "settings" menu from the bottom left panel:

mafbx-param

Allow remote access to your box:

mafbx-param-axx

Now you're ready to configure your domain name URL and TLS certificate

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

CONFIGURE DOMAIN NAME - URL - TLS CERTIFICATE

Access domain name menu:

mafbx-param-domain1

Set in the box the domain name you already configure in the prerequisite:

mafbx-param-domain2

Tic: "Yes I want to add a TLS certificate":

mafbx-param-domain3

Select your certificate type (RSA/ECDSA) and fulfill all fields like on the picture:

mafbx-param-domain4

Done! Don't forgot to select your new domain as the "DEFAULT DOMAIN"

mafbx-param-domain5

Select your new domain as the "DEFAULT DOMAIN":

mafbx-param-domain6

And now, verify your BOX's configuration is fine:

fbx_remote_axx

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES

ASK FOR A FULL-STACK IPv4 PUBLIC IP ADDRESS

Shared public IPv4 and NAT troubles:

Today, when your connection IS NOT IN BRIDGE MODE but is in ROUTER MODE, in France, Free Telecom from Iliad Group often deliver your internet connection with 1 fixed public IP shared for 4 people (=for 4 neighbourg connections) and Free will NAT 25% of the availiable ports of the public IP address shared with 4 customers to each of the 4 customer's connection.

That want to say that for the same public IP address,

If you are in this case and this situation is convinient for you (maybe you have ports from 1 to 16384 which let you disposed of the most usefull ports on internet which are ports less than 1024), you must BE CAREFULL when managing NAT redirection that the NAT redirection is not out of your assigned port range

In the same way, be carefull that your box internal services will not listen on standard port and maybe it can really be awkward in lots of situation, for example if you don't have ports 1 to 16384, it could be difficult to established some IPSEC tunnels with some enterprise class remote device peers which by design of the IPSEC protocole cannot change the IKE (UDP 500) target port when establishing an ipsec connection. This is a small example, but if you activate your box embed FTP server, you cannot use the port 21 for connection and ports 60000 to 65000 for pasive FTP ports (standard FTP configuration)

The number of outgoing session of your network will also be affected by this ip sharing, as each session is uniquely defined in linux kernel by the tuple of src port, src addr, dst addr, dst port, so having only 16384 availiable ports reduce by 4 the session capacity (assuming 50% of your 16384 ports are used for outgoing trafic) and result in session clash when heavy load or large number of clients on the local network.

If you have a normal use of your internet connection (if you read this README you may be a sort of 'advanced freebox/iliadbox user'), you may want to open ports and/or to host some services using standard internet ports and having only 25% of your public IP address ports can be awkwed for you. In this situation, you can ask (you may ask) the ISP for a "FULL STACK" public ip address and the ISP will give you a new public IPv4 address with all ports (1 to 65536).

To ask for a FULL-STACK ip address, you need to connect you customer account at your ISP website. If you are in France, please connect Login Free If you are in Italy, please connect Login Iliad

When you're connected, select your box tab (in France "Ma Freebox", maybe "My Iliadbox" in Italy) and see the advanced options. Click on the one which speak of full-stack ip address or something similar and follow the process

In France at the time I'm writing, this is FREE OF CHARGE !
Picture

fbx-full-stk

TOP TABLE OF CONTENTS TABLE OF EXTRAS EXTERNAL RESSOURCES