Storage API [UNSTABLE]

This API allows you to manage the Freebox internal disk and disks connected to the Freebox

This API is unstable, it can be modified without notice in next releases.

Storage API Errors

When attempting to access this API, you may encounter the following errors:

error_code	Description
not_found	No disk/partition with this id
invalid_disk	No such disk
is_a_partition	This is not a disk but a partition
is_internal	This action is not permitted on internal disk
op_not_supported	Operation not supported
op_failed	Operation failed
disk_busy	Disk is busy

Disk Partition object

Operation progress has the following attributes:

OperationProgress

done_steps int Read-only

number of steps done

max_steps int Read-only

total number of steps

percent int Read-only

current step progress

Disk partitions have the following attributes:

DiskPartition

id int Read-only

unique partition id

disk_id int Read-only

related disk id

state enum

state	Description
error	Partition has error
checking	Partition check in progress
formatting	Partition format in progress
mounting	Partition mount in progress
maintenance	Partition is in maintenance mode
mounted	Partition is ready
umounting	Partition umount in progress
umounted	Partition is umounted
ejecting	Partition ejection in progress

fstype enum Read-only

fstype
empty
unknown
xfs
ext4
vfat
ntf
hf
hfsplus
swap
exfat

label string

partition name

path string Read-only

partition mount point (encoded in base64 as explained in fs API)

total_bytes int Read-only

partition size (in bytes)

used_bytes int Read-only

partition used space (in bytes)

free_bytes int Read-only

partition free space (in bytes)

fsck_result enum Read-only

fsck result

state	Description
no_run_yet	Partition has not been checked yet
running	Check is in progress
fs_clean	File system is ok
fs_corrected	File system was corrected
fs_needs_correction	File system need correction
failed	File system has unrecoverable error

operation_pct OperationProgress Read-only

partition operation progress

Storage Disk object

Storage disks have the following attributes:

StorageDisk

id int Read-only

the disk id

type enum Read-only

type	Description
internal	Freebox internal disk
usb	usb disk
sata	sata disk

state enum

state	Description
error	Disk has error
disabled	Disk is disabled
enabled	Disk is enabled
formatting	Disk is formatting

connector int Read-only

Disk physical connector id

total_bytes int Read-only

Disk size (in bytes)

table_type int Read-only

table_type
msdos
gpt
superfloppy
empty

model string Read-only

Disk model

serial string Read-only

Disk serial number

firmware string Read-only

Disk firmware version

temp int Read-only

Disk temperature (when supported) in °C

operation_pct OperationProgress Read-only

partition operation progress

partitions[] array of DiskPartition Read-only

list of disk partitions

idle bool Read-only

is disk idle (when available)

idle_duration int Read-only

disk idle duration (in seconds) (when available)

spinning bool Read-only

is disk spinning (when available)

active_duration int Read-only

disk activity duration (in seconds) (when available)

time_before_spindown int Read-only

seconds left before disk spin down (in seconds) (when available)

Storage Disk API

Get the list of disks

GET /api/v4/storage/disk/

Returns the collection of all StorageDisk

Example request:

GET /api/v4/storage/disk/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": [
        {
            "idle_duration": 368,
            "spinning": true,
            "table_type": "msdos",
            "firmware": "PB2ICC0E",
            "type": "internal",
            "idle": true,
            "connector": 0,
            "id": 1,
            "state": "enabled",
            "time_before_spindown": 232,
            "total_bytes": 250059350016,
            "model": "Hitachi HCC545025B9A300",
            "active_duration": 0,
            "temp": 51,
            "serial": "GSCH35VC",
            "partitions": [
                {
                    "fstype": "ext4",
                    "total_bytes": 245091500032,
                    "label": "Disque dur",
                    "id": 3,
                    "fsck_result": "no_run_yet",
                    "state": "mounted",
                    "disk_id": 1,
                    "free_bytes": 68120969216,
                    "used_bytes": 164520534016,
                    "path": "L0Rpc3F1ZSBkdXI="
                }
            ]
        },
        {
            "type": "usb",
            "total_bytes": 125435904,
            "connector": 1,
            "id": 1001,
            "active_duration": 0,
            "partitions": [
                {
                    "fstype": "ext4",
                    "total_bytes": 121418752,
                    "label": "Disque 1",
                    "id": 1002,
                    "fsck_result": "no_run_yet",
                    "state": "mounted",
                    "disk_id": 1001,
                    "free_bytes": 108904448,
                    "used_bytes": 6245376,
                    "path": "L0Rpc3F1ZSAx"
                }
            ],
            "idle_duration": 0,
            "state": "enabled",
            "idle": false,
            "spinning": false,
            "model": "",
            "table_type": "gpt",
            "temp": 0,
            "serial": "",
            "firmware": ""
        }
    ]
}

Get a given disk info

GET /api/v4/storage/disk/{id}

Returns the StorageDisk with the given id

Example request:

GET /api/v4/storage/disk/1 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "idle_duration": 464,
        "spinning": true,
        "table_type": "msdos",
        "firmware": "PB2ICC0E",
        "type": "internal",
        "idle": true,
        "connector": 0,
        "id": 1,
        "state": "enabled",
        "time_before_spindown": 136,
        "total_bytes": 250059350016,
        "model": "Hitachi HCC545025B9A300",
        "active_duration": 0,
        "temp": 51,
        "serial": "GSCH35VC",
        "partitions": [
            {
                "fstype": "ext4",
                "total_bytes": 245091500032,
                "label": "Disque dur",
                "id": 3,
                "fsck_result": "no_run_yet",
                "state": "mounted",
                "disk_id": 1,
                "free_bytes": 68120969216,
                "used_bytes": 164520534016,
                "path": "L0Rpc3F1ZSBkdXI="
            }
        ]
    }
}

Update a disk state

PUT /api/v4/storage/disk/{id}

Enable/Disable a disk

Example request:

PUT /api/v4/storage/disk/1 HTTP/1.1
Host: mafreebox.freebox.fr

{
   "state": "disabled"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "type": "usb",
        "total_bytes": 125435904,
        "connector": 1,
        "id": 1001,
        "active_duration": 0,
        "partitions": [
            {
                "fstype": "ext4",
                "total_bytes": 121418752,
                "label": "Disque 1",
                "id": 1002,
                "fsck_result": "no_run_yet",
                "state": "umounted",
                "disk_id": 1001,
                "free_bytes": 108904448,
                "used_bytes": 6245376,
                "path": "L0Rpc3F1ZSAx"
            }
        ],
        "idle_duration": 0,
        "state": "disabled",
        "idle": false,
        "spinning": false,
        "model": "",
        "table_type": "gpt",
        "temp": 0,
        "serial": "",
        "firmware": ""
    }
}

Format a disk

PUT /api/v4/storage/disk/{id}/format/

Format the disk with the given id

To be able to format a disk you need to provide the following parameters (JSON encoded). There will be one partition using all the available space on disk. All previous data will be lost.

This parameters will be ignored if you format the Freebox internal disk

Parameters:

• table_type (string) – The partition table format
• fs_type (string) – The partition type
• label (string) – The partition label

NOTE: once started you can monitor the format process getting the disk information (see StorageDisk operation_pct field)

Example request:

PUT /api/v4/fs/storage/disk/1001/format HTTP/1.1
Host: mafreebox.freebox.fr

{
   "label": "freebox",
   "fs_type": "vfat",
   "table_type": "msdos"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true
}

Storage Partition API

Get the list of partitions

GET /api/v4/storage/partition/

Returns the collection of all DiskPartition

Example request:

GET /api/v4/storage/partition/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": [
        {
            "fstype": "ext4",
            "total_bytes": 245091500032,
            "label": "Disque dur",
            "id": 3,
            "fsck_result": "no_run_yet",
            "state": "umounted",
            "disk_id": 1,
            "free_bytes": 68120969216,
            "used_bytes": 164520534016,
            "path": "L0Rpc3F1ZSBkdXI="
        },
        {
            "fstype": "vfat",
            "total_bytes": 123485184,
            "label": "freebox",
            "id": 1002,
            "fsck_result": "no_run_yet",
            "state": "mounted",
            "disk_id": 1001,
            "free_bytes": 123484672,
            "used_bytes": 512,
            "path": "L2ZyZWVib3g="
        }
    ]
}

Get a given partition info

GET /api/v4/storage/partition/{id}

Returns the DiskPartition with the given id

Example request:

GET /api/v4/storage/partition/1002 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "fstype": "vfat",
        "total_bytes": 123485184,
        "label": "freebox",
        "id": 1002,
        "fsck_result": "no_run_yet",
        "state": "mounted",
        "disk_id": 1001,
        "free_bytes": 123484672,
        "used_bytes": 512,
        "path": "L2ZyZWVib3g="
    }
}

Update a partition state

PUT /api/v4/storage/partition/{id}

Enable/Disable a partition

Example request:

PUT /api/v4/storage/partition/1 HTTP/1.1
Host: mafreebox.freebox.fr

{
   "state" : "umounted"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "fstype": "vfat",
        "total_bytes": 123485184,
        "label": "freebox",
        "id": 1002,
        "fsck_result": "no_run_yet",
        "state": "umounted",
        "disk_id": 1001,
        "free_bytes": 123484672,
        "used_bytes": 512,
        "path": "L2ZyZWVib3g="
    }
}

Check a partition

PUT /api/v4/storage/partition/{id}/check/

Checks the partition with the given id

To be able to check a partition you need to provide the following parameters (JSON encoded):

Parameters:

• checkmode (enum) – ‘ro’ for read only check, ‘rw’ to attempt to repair errors

NOTE: once started you can monitor the fsck process getting the partition information (see DiskPartition operation_pct field)

Example request:

PUT /api/v4/fs/storage/partition/1002/check HTTP/1.1
Host: mafreebox.freebox.fr

{
   "checkmode": "ro"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true
}

Storage Config

StorageConfig has the following attributes:

StorageConfig

external_pm_enabled bool

enable/disable external disk power management

external_pm_idle_before_spindown int

idle time in minutes to wait before spinning down an external disk

Storage config API

Get the current storage configuration

GET /api/v4/storage/config/

Get the StorageConfig

Example request:

GET /api/v4/storage/config/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "success": true,
  "result": {
     "external_pm_idle_before_spindown": 10,
     "external_pm_enabled": true
  }
}

Update the External Storage configuration

PUT /api/v4/storage/config/

Update the StorageConfig

Example request:

PUT /api/v4/storage/config/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "external_pm_enabled": false
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "external_pm_idle_before_spindown": 10,
        "external_pm_enabled": false
    }
}