Skip to content

nbanb/fbx-delta-nba_bash_api.sh

BranchesTags
 
 

Repository files navigation

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

  • 100% BASH

  • APIv12 (FREEBOX) / APIv12 (PLAYER)

  • USE AT YOUR OWN RISK



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 - sourcing library 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 managing DOMAIN NAME DOMAIN NAME FUNCTIONS
frontend Functions for formatting API reply of frontend functions API REPLY OUTPUT
core frontend Functions for listing Freebox components from API API LISTING
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

4. External tools needed to use this library

Type Name Description Link
$${\color{red}\text{Required}}$$ $${\color{red}\text{ curl }}$$ $${\color{red}\text{needed for all API call}}$$ curl
$${\color{red}\text{Required}}$$ $${\color{red}\text{ openssl }}$$ $${\color{red}\text{needed for authentication}}$$ openssl
$${\color{red}\text{Required}}$$ $${\color{red}\text{ coreutils }}$$ issue#9 $${\color{red}\text{basic Unix / Linux tools}}$$ GNU coreutils
$${\color{red}\text{Required}}$$ $${\color{red}\text{ file }}$$ issue#9 $${\color{red}\text{needed to detect PEM certificates}}$$ file
$${\color{orange}\text{VM required}}$$ $${\color{orange}\text{ websocat }}$$ $${\color{orange}\text{needed to use websocket API (VM console...)}}$$ websocat
$${\color{orange}\text{VM required}}$$ $${\color{orange}\text{ tigervnc }}$$ $${\color{orange}\text{needed to access VM screen over websocket}}$$ tigervnc
$${\color{yellow}\text{VM optional }}$$ $${\color{yellow}\text{ screen }}$$ $${\color{yellow}\text{allow to launch VM console in a SCREEN}}$$ GNU screen
$${\color{yellow}\text{VM optional }}$$ $${\color{yellow}\text{ dtach }}$$ $${\color{yellow}\text{allow to launch VM console detached from terminal}}$$ GNU dtach
$${\color{lightgreen}\text{Recommended}}$$ $${\color{lightgreen}\text{ jq }}$$ $${\color{lightgreen}\text{needed for fast json parsing}}$$ jq

NOTE :

$${\color{red}\text{To use this library you must install (at least) :}}$$ $${\color{red}\text{- curl}}$$ $${\color{red}\text{- openssl}}$$ $${\color{red}\text{- file}}$$ $${\color{red}\text{- coreutils}}$$ $${\color{red}\text{You should use your distribution package manager to install those tools.}}$$

$${\color{orange}\text{If you want to use VM functions, you will have to install websocat + tigervnc.}}$$ $${\color{lightgreen}\text{If jq is installed, it will be used to speed-up functions which need to run faster.}}$$


TOP TABLE OF CONTENTS EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

Quick Start

You need to have curl and openssl installed (see EXTERNAL TOOLS).

  • Get the source:

$ 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:

Edit fbx-delta-nba_bash_api.sh and set a password for:

_APP_PASSWORD=""

If you are in Italy, set

ITALY="yes"

  • Configure URL (optional but needed to access API over internet)

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"

  • Get an application token for API access (APP_ID and APP_TOKEN)

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 and use lirary functions:

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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

API

NOTE
  • Some underlying functions used by other functions of the API may NOT be listed in this README but you have here the most important functions for writing an application and for direct use in your bash cmdline.
  • Frontend functions listed above can be used directlly like an end user program as they include their own check parameters engine and error / help output and when necessary tasks monitoring and task management.

API USAGE: SOURCING LIBRARY

Sourcing this library support 3 modes :

  • help
  • list
  • <empty> : this mode (no parameters) is the $${\color{red}\text{normal mode}}$$
NOTE :

$${\color{red}\text{SOURCING LIBRARY WITH HELP OR LIST OPTION DON'T SOURCE FUNCTIONS}}$$

**help parameter

This mode will output a summary of help

Example
source fbx-delta-nba_bash_api.sh --help
To source all library functions source without parameters (standard use):
Example: 
	 source ./fbx-delta-nba_bash_api.sh 

Sourcing library with 'help' or 'list' parameters DOES NOT source library ! 
Parameters:
	  -h,--h,help,-help,--help	- print this help
	  -l,--l,list,-list,--list	- print a list of all functions of the library
Example: 
	  source ./fbx-delta-nba_bash_api.sh --help
	  source ./fbx-delta-nba_bash_api.sh --list 

HELP: 
	  - To get help and example, please read the attached README.md file or the code
	  - All frontend functions have their embedded help (run function with no parameters)
	    Example: 
	    source ./fbx-delta-nba_bash_api.sh
	    login_freebox "$MY_APP_ID" "$MY_APP_TOKEN" && add_dhcp_static_lease
	  - You can access online help here : 
	  https://github.com/nbanb/fbx-delta-nba_bash_api.sh 

SUPPORT: 
	  - Support is availiable @ GitHub.com 
	  - You can open issues here : 
	  https://github.com/nbanb/fbx-delta-nba_bash_api.sh/issues/new
Picture

image

**list parameter

This mode will output a list of all function and where to find functions help

Example
source fbx-delta-nba_bash_api.sh --list
fbx-delta-nba_bash_api.sh functions listing on: 2024-10-21

add_dhcp_static_lease                     add_dl_task_api                  add_freebox_api
add_fw_redir                              add_share_link                   app_login_freebox
archive_fs_file                           authorize_application            auto_relogin
call_freebox_api                          call_freebox_api2                call_freebox-ws_api
call_freebox-ws_vnc                       check_and_feed_dhcp_param        check_and_feed_dl_param
check_and_feed_domain_param               check_and_feed_fs_param          check_and_feed_fs_task_param
check_and_feed_fw_redir_param             check_and_feed_share_link_param  check_and_feed_vm_action_param
check_and_feed_vm_prebuild_distros_param  check_and_feed_wol_param         _check_freebox_api
check_if_domain                           check_if_ip                      check_if_mac
check_if_port                             check_if_rfc1918                 check_login_freebox
_check_success                            _check_success2                  _check_success_old
check_tool                                check_tool_exit                  check_vm_param
colorize_output                           colorize_output_pretty_json      cp_fs_file
cp_fs_file_raw                            create_vm_variables              ctrlc
ctrlc_trap                                del_bundle_cert_file             del_dhcp_static_lease
del_dl_task_api                           del_freebox_api                  del_fs_file
del_fs_task                               del_fw_redir                     del_share_link
dis_fw_redir                              dl_task_log_api                  dl_vm_prebuild_distros
domain_add                                domain_addcert                   domain_del
domain_list                               domain_setdefault                dump_json_keys_values
ena_fw_redir                              enc_dl_task_api                  extract_fs_file
feeds_vmdisk_variables                    full_vm_detail                   get_freebox_api
get_fs_task                               get_json_value_for_key           get_json_value_for_key2
get_share_link                            get_vm_object_var                hash_fs_file
hash_fs_task                              list_dhcp_static_lease           list_dl_task_api
list_domain                               list_fs_file                     list_fs_task_api
list_fw_redir                             list_player                      list_repeater
list_share_link                           list_vm                          list_vm_prebuild_distros
local_direct_dl_api                       login_fbx                        login_fbx2
login_freebox                             logout_freebox                   ls_fs
mk_bundle_cert_file                       mkdir_fs_file                    modify_vm_variables
mon_fs_task_api                           monitor_dl_task_adv_api          monitor_dl_task_api
mv_fs_file                                param_dhcp_err                   param_dom_fbx_err
param_download_err                        param_fs_err                     param_fs_task_err
param_fw_redir_err                        param_share_link_err             param_vm_action_err
param_vm_disk_err                         param_vm_prebuild_distros_err    param_wol_fbx_err
_parse_and_cache_json                     _parse_array                     _parse_json
_parse_object                             _parse_value                     player_list
post_fbx_api                              print_err                        print_term_line
progress                                  put_fbx_api                      reboot_freebox
relogin_freebox                           rename_fs_file                   repeater_list
rm_fs_file                                show_dl_task_api                 show_fs_task
show_share_link                           shutdown_freebox                 status_freebox
_throw                                    _throw_nba                       _tokenize_json
update_freebox_api                        upd_dhcp_static_lease            upd_dl_task_api
upd_fbx_api                               upd_fs_task                      upd_fw_redir
vm_add                                    vm_adddisk                       vm_console
vm_deldisk                                vm_delete                        vm_detail
vm_list                                   vm_listdisk                      vm_modify
vm_param                                  vm_reload                        vm_resizedisk
vm_resource                               vm_restart                       vm_sconsole
vm_show                                   vm_shutdown                      vm_start
vm_stop                                   vm_svnc                          vm_vnc
websocat_session                          wol_fbx                          wrprogress
ws_session                                                                 

Sourcing library with 'list' parameters DOES NOT source library functions ! 

To source all library functions source without parameters:
Example: 
	 source ./fbx-delta-nba_bash_api.sh 


FUNCTIONS HELP: 
	  - To get help and example, please read the attached README.md file or the code
	  - All frontend functions have their embedded help (run function with no parameters)
	    Example: 
	    source ./fbx-delta-nba_bash_api.sh
	    login_freebox "$MY_APP_ID" "$MY_APP_TOKEN" && add_dhcp_static_lease
	  - You can access online help here : 
	  https://github.com/nbanb/fbx-delta-nba_bash_api.sh 

SUPPORT: 
	  - Support is availiable @ GitHub.com 
	  - You can open issues here : 
	  https://github.com/nbanb/fbx-delta-nba_bash_api.sh/issues/new
Picture

image image

NOTE :

$${\color{red}\text{TO USE LIBRARY FUNCTIONS SOURCE LIBRARY WITH NO PARAMETERS}}$$

Example
source fbx-delta-nba_bash_api.sh
TOP TABLE OF CONTENTS EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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 :

  • Your applications APP_ID and APP_NAME and APP_VERSION and DEVICE_NAME will be scrolling on the Freebox LCD (sorry for the picture, application name scrolling on the LCD is fast, I didn't succeed in taking a readable picture)

fbx-vapp

  • Select the tic to validate

fbx-val0

  • You must see 'YES' displayed on the LCD in your box current language (in France you will see 'OUI')
  • If needed, tic again to validate

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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

* 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

* auto_relogin

After a first sucessfull login using function 'login_freebox', this function will try to detect _APP_ENCRYPTED_TOKEN in the environment and will relogin the application if _APP_ENCRYPTED_TOKEN exist.
Return 0 if success, 1 otherwise

Example
auto_relogin
TOP TABLE OF CONTENTS EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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')

* call_freebox-ws_vnc api_path

It is used to call a freebox Websocket API with websocket request and to connect local VNC tcp socket. It need you install 'websocat' from websocat and to install 'tigervnc' from TigerVNC. The function will return a websocket interractive connection which piped Qemu VNC websocke. It 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_vnc '/vm/8/vnc')

* 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')

* get_json_value_for_key_jq json_string key

This function will return the value for the key from the json_string This function is the same as get_json_value_for_key but using jq parser https://jqlang.github.io/jq/

This function is used when direct json query is needed (without caching json "keys values"). It is 20 times faster than get_json_value_for_key but needed you install jq parser

Example
value=$(get_json_value_for_key_jq "$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

* dump_json_keys_values_jq json_string

This function will dump on stdout all the keys values pairs from the json_string This function is the same as dump_json_keys_values but using jq parser https://jqlang.github.io/jq/

This function is used to cache results and is 20 times faster than dump_json_keys_values but needed you install jq parser

Example
answer=$(call_freebox_api '/connection/')
dump_json_keys_values_jq "$answer"
echo
bytes_down=$(get_json_value_for_key_jq "$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}

* _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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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 $?

* check_if_domain string

This function will check if the provided argument is a domain name (only REGEX check on syntaxe, no DNS request). Return code will be 0 if the provided argument is a DOMAIN NAME, and will exit with a return code of 1 if argument is not a valid DOMAIN NAME.

Example
check_if_domain test.freebox.lan
echo $?

* check_if_url string

This function will check if the provided argument is a valid URL composed by a domain name (only REGEX check on syntaxe, no DNS request) and a prefix like https://. Return code will be 0 if the provided argument is a valid URL, and will exit with a return code of 1 if argument is not a valid URL.

Note

Supported prefixes: http,https,ftp,ftps,ftpes,sftp,ws,wss

Example
check_if_url wss://test.freebox.lan
echo $?
TOP TABLE OF CONTENTS EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

API FRONTEND - MINDSET

  • The new FRONTEND functions of this library are usable directly as if they were some complete command or program
  • For all categories of API for which some frontend functions had been developped (DOWNLOAD, FILESYSTEM,...) you will always find the same mechanisme :
    • Each categories has a listing function which can list API Objects or API Tasks
    • Each categories has a 'check_and_feed_XXX_param' for validating the arguement parameters and syntax
    • Each categories has a 'param_XXX_err' function which manage errors and print help / examples when necessary
    • Each function had a nice human readable output
TOP TABLE OF CONTENTS EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

DOWNLOAD API - EXTRA

LETS WRITE A SMALL PROGRAM FOR DOWNLOADING:

  • Our small program will
    • create a download task for downloading a file
    • show our newly launched task
    • monitor the download
    • monitor the checksum checking task
    • print download task log
    • show our finished task
    • delete our finished task
# 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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

API FRONTEND FUNCTIONS - DIRECT DOWNLOAD

  • This API only provide the possibility to download files present on freebox starage (NAS) directly on the computer running this function
    • This function make an authenticted call to the API
    • This function let you download files with NO restrictions
    • You do not need a valid "share link" to be able to download a file

* 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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

API FRONTEND FUNCTIONS - DOWNLOAD SHARE LINK

  • This API only provide the possibility to create non authentified download share link to publish stuff present on your Freebox storage (NAS) on internet.
    • Files are accessible over an unauthenticated call to the API on a particular URL
    • This API let you manage download share links (list, create, delete)
    • You can set an expiration date on each created 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

  • If you have a Freebox Delta and you run Virtual Machines inside your Freebox Delta, you can install and build a custom VM image with all requirements needed to make work the service this VM will deliver (ex: home automation server, home web server, home TOR bridge, home Media server ...), and when your VM image is ready, you can decide to share it to Freebox Delta VM user's community So you can stop your VM and copy the disk image to a "public" directory you create on Freebox storage for this use And you can create a share link which let people access to the copy of the VM image you've just done and you can post this share link on public forums. As you can set an expiration date on each lnk, if you decide to provide the community rolling upgrade of your VM image (weekly or monthly), you can make all links valid only until the next rolling upgrade release you will provide to the community.

  • Sometimes, you may want to send an email with a big archive attached, but the attached files are too big for beeing accepted by remote SMTP server (don't forgot to encrypt and put a password on the archive before sending it over internet). Here you can use a share link:

    • Put your attached archives in a directory of your Freebox storage
    • Create share links for all differents archives
    • Copy paste those share links in your mail and the destination people will be able to download the content target of share links you send them.
WARNING
  • To maintien PRIVACY in this README, I'm masking the public URL and PORT in the share links I will publish here because it's pointing to a REAL Freebox reachable over the internet.
  • To do so, I will replace in all URL my public domain by 'my-public-domain.net' and the port by '4011', using something like:
show_share_link l1i-SuYthQC8bjKo |sed -e "s/${mydom}/my-public-domain.net/g" -e "s/${myport}/4011/g"

* 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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

API FRONTEND FUNCTIONS - NETWORK: DHCP

  • This API only provide the possibility to manage DHCP reservations and allow you to assign a predifined IP address to a particular MAC address
  • Functions developped to manage this API let you list, add, update and delete DHCP reservation and the list command also show you if some reservations are currently used (when assigned IP is reachable)
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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

API FRONTEND FUNCTIONS - NETWORK: NAT REDIRECTIONS

  • This API only provide the possibility to manage IPv4 destination NAT redirections and allow you open a port of your public IP and bind it to a local port of a local ip address. This way you can host some service on your network and make them accessibles on internet
  • Functions developped to manage this API let you list, add, update, enable, disable and delete your box destination NAT redirections and the list command also show you the status (enabled or disabled) of each destination 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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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:

  • You want to build / start a VM for a particular service
  • You also want to publish and share your VM image (after adding inside your own configuration) to other Freebox Delta users

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

  • You will have to download a VM image or an ISO for installing your VM
    • so you need to use the function which manage the download API
  • Maybe you will download a compressed archive
    • so you will need to extract it before using it
    • Maybe you will need to create directories, remove source archive...

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

  • You will have to publish a copy of your VM disk image
    • so you will need to temporary stop your VM
    • you will need to copy the VM disk image
    • you will need to create a 'public' directory
    • maybe you will need to create an archive
  • You may need to move the newly created archive to your public directory
    • and you will need to create a share link with the share link functions of the library Finaly, you can publish / post your share link to others users on some forums, ...

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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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="/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

  • it does not accept boolean options (onlyFolder & removeHidden)
  • by design, when directory listing is big, suffer of performance issue
  • if we need to retrieve 10 values on 100 files this function will do 1000 API call to get the result...

$${\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="/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="/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="/FBXDSK/vm/archive.zip" dst="/FBXDSK/vm" 

EXAMPLE (medium):
extract_fs_file src="/FBXDSK/vm/archive.zip" dst="/FBXDSK/vm" password="MyArchivePassword" 

EXAMPLE (full):
extract_fs_file src="/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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

API FRONTEND FUNCTIONS - DOMAIN NAME

You must notice that today, this API is not documented. As describes in the Freebox developper documentation, UNDOCUMENTED API MUST NOT BE USED !

But as it's really boring to go to FreeboxOS web interface to define domains and upload certificates, I decide to implement this functionnality. At the time I'm writing (end of 2024), it's working well, but please $${\color{red}\text{USE AT YOUR OWN RISK }}$$


Note :
$${\color{red}\text{UNDOCUMENTED API MUST NOT BE USED ! }}$$

New :
--> Function domain_setdefault let you define Freebox default domain name (used for remote @ access)
--> listing domain name support auto_relogin

New DOMAIN functions supported :

function : description
$${\color{red}\text{Calling function with no parameters will print help }}$$
domain_list list Freebox configured domain
domain_add add a new domain name on Freebox
domain_del delete a configured domain name on Freebox
domain_addcert add a TLS certificat to a configured Freebox domain
domain_setdefault set Freebox default domain name (used for remote access)

* domain_list

This function will simply retrieve the list of configured domains

Example
domain_list
			DOMAIN ID, TYPE, OWNER, CERTIFICAT DAYS LEFT 
--------------------------------------------------------------------------------------------------------------
DOMAIN-0:	owner: user	type: custom	rsa: none 	ecdsa: 105	domain id : sba.xxxxxxx.net 
DOMAIN-1:	owner: user	type: custom	rsa: 105 	ecdsa: none	domain id : 14rv.xxxxxxx.net 
DOMAIN-2:	owner: user	type: custom	rsa: 59 	ecdsa: none	domain id : fbx.fbx.lan 
DOMAIN-3:	owner: user	type: custom	rsa: none 	ecdsa: 105	domain id : test.14rv.lan 
DOMAIN-4:	owner: user	type: custom	rsa: none 	ecdsa: 105	domain id : 14rv-fbx.fbx.lan 
DOMAIN-5:	owner: user	type: custom	rsa: 80 	ecdsa: none	domain id : fbx.my-public-domain.net 
DOMAIN-6:	owner: user	type: custom	rsa: none 	ecdsa: 105	domain id : home.xxxxxxx.net 
DOMAIN-7:	owner: user	type: custom	rsa: none 	ecdsa: 105	domain id : test.xxxxxxx.lan 
DOMAIN-8:	owner: freebox	type: auto	rsa: 57 	ecdsa: 57	domain id : xxxxxxx.fbxos.fr 
DOMAIN-9:	owner: user	type: custom	rsa: none 	ecdsa: 105	id default: fbx.xxxxxxx.net 
DOMAIN-10:	owner: user	type: custom	rsa: none 	ecdsa: 105	domain id : lba.xxxxxxx.net 
DOMAIN-11:	owner: user	type: custom	rsa: none 	ecdsa: 105	domain id : fbx.14rv.lan 
DOMAIN-12:	owner: user	type: custom	rsa: none 	ecdsa: none	domain id : test.com
Picture

Capture db��C)cran du 2024-10-19 12-29-47

* domain_add

This function will simply add a domains to the list of configured domains

Example
domain_add
ERROR: <param> must be :
id			# id must be a domain name

NOTE: you can get a list of all configured domain and status (showing all 'id'), just run: 
domain_list

EXAMPLE:
domain_add id=my.domain.com
Picture

image

domain_add id=test.fbx.lan
operation completed: 
{"success":true}

result:
{"id":"test.fbx.lan","type":"custom","certs":{},"owner":"user"}
Picture

image

* domain_del

This function will simply delete a domains from configured Freebox domains

Example
domain_del
ERROR: <param> must be :
id          # id must be a domain name

NOTE: you can get a list of all configured domain and status (showing all 'id'), just run:
domain_list

EXAMPLE:
domain_del id=my.domain.com
Picture

image

domain_del id=test.fbx.lan
operation completed:
{"success":true}
Picture

image

* domain_addcert

This function will add a TLS certificate to a configured domain name

Example
domain_addcert
ERROR: <param> must be :
id			# id must be a domain name
key_type		# key_type is 'ed' or 'rsa'
cert_pem		# path to file containing your certificat in PEM format
key_pem			# path to file containing your certificat PRIVATE KEY in PEM format
intermediates		# path to file containing your root or intermediate CA certificat in PEM format

NOTE: you can get a list of all configured domain and status (showing all 'id'), just run: 
domain_list

NOTE: your certificate files (+ intermediate) files must contains: 
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
AND for key PEM files:
-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----

EXAMPLE (PEM files are stored in current directory):
domain_addcert id="my.domain.com" key_type="ec" cert_pem="mycert.pem" key_pem="mykey.pem" intermediates="myintermediateCA.pem"  

EXAMPLE (PEM files are stored in CERT/ directory):
domain_addcert id="my.domain.com" key_type="ec" cert_pem="CERT/mycert.pem" key_pem="CERT/mykey.pem" intermediates="CERT/myintermediateCA.pem"
Picture

image

domain_addcert id=test.fbx.lan key_type=ec cert_pem=CERT/14rv-RSA8192_2023-crt.pem key_pem=CERT/14rv-RSA8192_2023-key.pem intermediates=CERT/14rv-rootCA-RSA8192.pem 
operation completed: 
{"success":true}
Picture

image


TOP TABLE OF CONTENTS EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

API LISTING FUNCTIONS - LISTING FREEBOX COMPONENTS

To be able to interract with other "freebox" plugged devices API, it's necesary to list them


Note :
$${\color{red}\text{LISTING OUTPUT COLOR CHANGE IF DEVICE IS ONLINE OR OFFLINE}}$$

Listing player device :

Example
list_player
Or
player_list
			ID, PLAYER NAME, PLAYER MODEL, PLAYER API VERSION
----------------------------------------------------------------------------------------------------
PLAYER-0:	id: 17  mac: 34:27:92:80:29:7c  model: fbx7hd-delta  api: 12.0  name: Freebox Player

Player ONLINE :

Picture

image

Player OFFLINE :

Picture

image

Listing wireless repeater device :

Note :
$${\color{red}\text{LISTING OUTPUT COLOR CHANGE IF DEVICE IS ONLINE OR OFFLINE}}$$

Example
list_repeater
Or
repeater_list
			ID, REPEATER NAME, REPEATER MODEL, REPEATER API VERSION
---------------------------------------------------------------------------------------------------------
REPEATER-1:  id: 1  ip: 192.168.100.89  mac: 8C:97:EA:55:BB:B6  model: fbxwmr-r1  api: 2  name: EntrC)e

Repeater ONLINE :

Picture

image

Repeater OFFLINE :

Picture

image


TOP TABLE OF CONTENTS EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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:

  • GREEN if operation is successfull
  • RED if operation failed
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:

  • GREEN if operation is successfull
  • RED if operation failed

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:

  • awk '$2 ~ /00:01:02:03:04:05/' or by
  • sed '/00:01:02:03:04:05/!d'

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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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

* shutdown_freebox

This function will shutdown 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
shutdown_freebox

* wol_fbx

This function is able to WAKE-ON-LAN a machine which had previously be configured (in UEFI BIOS stack) to start when recieving a "wake-on-lan". Return code will be 0 if the signal had been send 1 otherwise and 130 if command parameters failed to be parsed. Your application must be granted to modify the setup of the freebox to use WAKE-ON-LAN function (from freebox web interface, see: GRANT API ACCESS)

Example
wol_fbx
ERROR: <param> for wol_fbx must be some of:
mac=
password=

NOTE: minimum parameters to specify on cmdline to Wake On LAN a machine: 
mac= 
password=  

NOTE: Wake On LAN password length seems to be 6 char max !

EXAMPLE:
wol_fbx mac="00:01:02:03:04:05" password="passwd"

EXAMPLE (EMPTY PASSWORD...):
wol_fbx mac="00:01:02:03:04:05" password=""
wol_fbx mac=00:01:02:03:04:05 password=
Picture

image

Example
wol_fbx mac=01:00:5e:00:00:fb password=test123
operation completed: 
{"success":true}
Picture

image

TOP TABLE OF CONTENTS EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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

  • To access some of the different API, your application MUST be granted for all tasks / API it will call. For example, to reboot your Freebox using the API, your application which call function 'reboot_freebox' must be granted to "modify freebox settings".
  • The way to grant an application to an API categorie is to login your box OS (at the time I'm writing, FreeboxOS or IliadboxOS)
    • connect your box OS (1),
    • put your password (2)
    • and click LOGIN (3)

mafbx

  • Access the "settings" (or "parameters") menu from the bottom left panel:

mafbx-param

  • and to go to the advanced tab of the "parameters menu"
    • select (at the bottom) the RBAC menu
    • go to the "application" tab of this newly opened window
    • edit your application access right

See the following capture:

fbx-app-axx

TOP TABLE OF CONTENTS EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

PUBLIC URL - TLS CERTIFICATE - API REMOTE ACCESS

  • Some of the API require you have a public URL (ex: download share links)
  • Remote access to your freebox over internet (from everywhere) require you have a public URL
  • This library support LAN, WAN and preconfigured DEFAULT URL and associated TLS certificates

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 - Buy a domain name (type "buy domain name" in google.com) - Configure a DNS 'A' record of your domain to point to your Freebox, example: - domain name= my-public-domain.net - freebox on domain= fbx.my-public-domain.net - freebox IP address= 82.82.82.82 - DNS zone entry to add to my-public-domain.net in this example:

fbx         IN        A       82.82.82.82
TOP TABLE OF CONTENTS EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

TLS CERTIFICATE

You also need a TLS certificate configured for your new domain fbx.my-public-domain.net - You can buy such TLS certificate to a public Certificate Authority - You can obtain a FREE TLS certificate at site like letsencrypt.org - Or you can create your own Root CA Certificate and issue Certificate from it, see CreateMyRootCA

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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

CONFIGURE REMOTE ACCESS

Login to your box OS:

  • connect your box OS (1),
  • put your password (2)
  • and click LOGIN (3)

mafbx

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

mafbx-param

Allow remote access to your box:

  • click the "advanced tab" (3) of the "setting menu" (2)
  • click "configuration" (4)
  • you can allow ping (5)
  • you must tic "allow password authentication" (6)
  • you must fulfill a custom HTTPS port (7)

mafbx-param-axx

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

TOP TABLE OF CONTENTS EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

CONFIGURE DOMAIN NAME - URL - TLS CERTIFICATE

Access domain name menu:

  • connect your box OS (1),
  • click the "advanced tab" (3) of the "setting menu" (2)
  • select "domain names" (4)
  • click "add a domain name" (5)
  • tic the box: "I want to add a domain I have already configured" (6)
  • click "Go" (7)

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:

  • Certificate (public key)
  • Certificate Private Key
  • In the last field, put the certificate chain of certificate issuer OR if you'r using your own PKI, put here your Root CA Certificate

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:

  • go to the "advanced tab" (1) of the "setting menu"
  • click "Role Based Access Control" (2)
  • verify the 'PORT' is the one you previously set in the other menu (3), if not set the same value
  • verify the 'Password Remote Access' box is tic (4), if not tic it
  • verify the URL for the remote access (5): it must be the one you've just configured
  • verify you can obtain new application tokens to access API (6)

fbx_remote_axx

TOP TABLE OF CONTENTS EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

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,

  • one customer have ports 1 to 16384
  • the second customer have ports 16385 to 32768
  • the third customer have ports 32768 to 49152
  • the second customer have ports 49152 to 65536

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 EXTRAS EXTERNAL RESSOURCES EXTERNAL TOOLS

About

Access FreeboxOS API from bash

Topics

api bash vm library download dhcp network delta freebox freebox-server websocat freebox-delta freebox-download iliadbox

Resources

Readme

License

View license
Activity

Stars

3 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Shell 100.0%