API extensions

The changes below were introduced to the LXD API after the 1.0 API was finalized.

They are all backward compatible and can be detected by client tools by looking at the api_extensions field in GET /1.0.

storage_zfs_remove_snapshots

A zfs.remove_snapshots daemon configuration key was introduced.

It’s a Boolean that defaults to false and that when set to true instructs LXD to remove any needed snapshot when attempting to restore another.

This is needed as ZFS will only let you restore the latest snapshot.

container_host_shutdown_timeout

A boot.host_shutdown_timeout container configuration key was introduced.

It’s an integer which indicates how long LXD should wait for the container to stop before killing it.

Its value is only used on clean LXD daemon shutdown. It defaults to 30s.

container_stop_priority

A boot.stop.priority container configuration key was introduced.

It’s an integer which indicates the priority of a container during shutdown.

Containers will shutdown starting with the highest priority level.

Containers with the same priority will shutdown in parallel. It defaults to 0.

container_syscall_filtering

A number of new syscalls related container configuration keys were introduced.

See Instance configuration for how to use them.

Note

Initially, those configuration keys were (accidentally) introduced with offensive names. They have since been renamed (container_syscall_filtering_allow_deny_syntax), and the old names are no longer accepted.

auth_pki

This indicates support for PKI authentication mode.

In this mode, the client and server both must use certificates issued by the same PKI.

See Security for details.

container_last_used_at

A last_used_at field was added to the GET /1.0/instances/<name> endpoint.

It is a timestamp of the last time the instance was started.

If an instance has been created but not started yet, last_used_at field will be 1970-01-01T00:00:00Z

etag

Add support for the ETag header on all relevant endpoints.

This adds the following HTTP header on answers to GET:

  • ETag (SHA-256 of user modifiable content)

And adds support for the following HTTP header on PUT requests:

  • If-Match (ETag value retrieved through previous GET)

This makes it possible to GET a LXD object, modify it and PUT it without risking to hit a race condition where LXD or another client modified the object in the meantime.

patch

Add support for the HTTP PATCH method.

PATCH allows for partial update of an object in place of PUT.

usb_devices

Add support for USB hotplug.

https_allowed_credentials

To use LXD API with all Web Browsers (via SPAs) you must send credentials (certificate) with each XHR (in order for this to happen, you should set withCredentials=true flag to each XHR Request).

Some browsers like Firefox and Safari can’t accept server response without Access-Control-Allow-Credentials: true header. To ensure that the server will return a response with that header, set core.https_allowed_credentials to true.

image_compression_algorithm

This adds support for a compression_algorithm property when creating an image (POST /1.0/images).

Setting this property overrides the server default value (images.compression_algorithm).

directory_manipulation

This allows for creating and listing directories via the LXD API, and exports the file type via the X-LXD-type header, which can be either file or directory right now.

container_cpu_time

This adds support for retrieving CPU time for a running container.

storage_zfs_use_refquota

Introduces a new server property zfs.use_refquota which instructs LXD to set the refquota property instead of quota when setting a size limit on a container. LXD will also then use usedbydataset in place of used when being queried about disk utilization.

This effectively controls whether disk usage by snapshots should be considered as part of the container’s disk space usage.

storage_lvm_mount_options

Adds a new storage.lvm_mount_options daemon configuration option which defaults to discard and allows the user to set additional mount options for the file system used by the LVM LV.

network

Network management API for LXD.

This includes:

  • Addition of the managed property on /1.0/networks entries

  • All the network configuration options (see Network configuration for details)

  • POST /1.0/networks (see RESTful API for details)

  • PUT /1.0/networks/<entry> (see RESTful API for details)

  • PATCH /1.0/networks/<entry> (see RESTful API for details)

  • DELETE /1.0/networks/<entry> (see RESTful API for details)

  • ipv4.address property on nic type devices (when nictype is bridged)

  • ipv6.address property on nic type devices (when nictype is bridged)

  • security.mac_filtering property on nic type devices (when nictype is bridged)

profile_usedby

Adds a new used_by field to profile entries listing the instances that are using it.

container_push

When an instance is created in push mode, the client serves as a proxy between the source and target server. This is useful in cases where the target server is behind a NAT or firewall and cannot directly communicate with the source server and operate in pull mode.

container_exec_recording

Introduces a new Boolean record-output, parameter to /1.0/instances/<name>/exec which when set to true and combined with with wait-for-websocket set to false, will record stdout and stderr to disk and make them available through the logs interface.

The URL to the recorded output is included in the operation metadata once the command is done running.

That output will expire similarly to other log files, typically after 48 hours.

certificate_update

Adds the following to the REST API:

  • ETag header on GET of a certificate

  • PUT of certificate entries

  • PATCH of certificate entries

container_exec_signal_handling

Adds support /1.0/instances/<name>/exec for forwarding signals sent to the client to the processes executing in the instance. Currently SIGTERM and SIGHUP are forwarded. Further signals that can be forwarded might be added later.

gpu_devices

Enables adding GPUs to a container.

container_image_properties

Introduces a new image configuration key space. Read-only, includes the properties of the parent image.

migration_progress

Transfer progress is now exported as part of the operation, on both sending and receiving ends. This shows up as a fs_progress attribute in the operation metadata.

id_map

Enables setting the security.idmap.isolated, security.idmap.size, and raw.idmap fields.

network_firewall_filtering

Add two new keys, ipv4.firewall and ipv6.firewall which if set to false will turn off the generation of iptables FORWARDING rules. NAT rules will still be added so long as the matching ipv4.nat or ipv6.nat key is set to true.

Rules necessary for dnsmasq to work (DHCP/DNS) will always be applied if dnsmasq is enabled on the bridge.

network_routes

Introduces ipv4.routes and ipv6.routes which allow routing additional subnets to a LXD bridge.

storage

Storage management API for LXD.

This includes:

  • GET /1.0/storage-pools

  • POST /1.0/storage-pools (see RESTful API for details)

  • GET /1.0/storage-pools/<name> (see RESTful API for details)

  • POST /1.0/storage-pools/<name> (see RESTful API for details)

  • PUT /1.0/storage-pools/<name> (see RESTful API for details)

  • PATCH /1.0/storage-pools/<name> (see RESTful API for details)

  • DELETE /1.0/storage-pools/<name> (see RESTful API for details)

  • GET /1.0/storage-pools/<name>/volumes (see RESTful API for details)

  • GET /1.0/storage-pools/<name>/volumes/<volume_type> (see RESTful API for details)

  • POST /1.0/storage-pools/<name>/volumes/<volume_type> (see RESTful API for details)

  • GET /1.0/storage-pools/<pool>/volumes/<volume_type>/<name> (see RESTful API for details)

  • POST /1.0/storage-pools/<pool>/volumes/<volume_type>/<name> (see RESTful API for details)

  • PUT /1.0/storage-pools/<pool>/volumes/<volume_type>/<name> (see RESTful API for details)

  • PATCH /1.0/storage-pools/<pool>/volumes/<volume_type>/<name> (see RESTful API for details)

  • DELETE /1.0/storage-pools/<pool>/volumes/<volume_type>/<name> (see RESTful API for details)

  • All storage configuration options (see Storage configuration for details)

file_delete

Implements DELETE in /1.0/instances/<name>/files

file_append

Implements the X-LXD-write header which can be one of overwrite or append.

network_dhcp_expiry

Introduces ipv4.dhcp.expiry and ipv6.dhcp.expiry allowing to set the DHCP lease expiry time.

storage_lvm_vg_rename

Introduces the ability to rename a volume group by setting lvm.vg_name.

storage_lvm_thinpool_rename

Introduces the ability to rename a thin pool name by setting lvm.thinpool_name.

network_vlan

This adds a new vlan property to macvlan network devices.

When set, this will instruct LXD to attach to the specified VLAN. LXD will look for an existing interface for that VLAN on the host. If one can’t be found it will create one itself and then use that as the macvlan parent.

image_create_aliases

Adds a new aliases field to POST /1.0/images allowing for aliases to be set at image creation/import time.

container_stateless_copy

This introduces a new live attribute in POST /1.0/instances/<name>. Setting it to false tells LXD not to attempt running state transfer.

container_only_migration

Introduces a new Boolean container_only attribute. When set to true only the instance will be copied or moved.

storage_zfs_clone_copy

Introduces a new Boolean zfs.clone_copy property for ZFS storage pools. When set to false copying an instance will be done through zfs send and receive. This will make the target instance independent of its source instance thus avoiding the need to keep dependent snapshots in the ZFS pool around. However, this also entails less efficient storage usage for the affected pool. The default value for this property is true, i.e. space-efficient snapshots will be used unless explicitly set to false.

unix_device_rename

Introduces the ability to rename the unix-block/unix-char device inside container by setting path, and the source attribute is added to specify the device on host. If source is set without a path, we should assume that path will be the same as source. If path is set without source and major/minor isn’t set, we should assume that source will be the same as path. So at least one of them must be set.

storage_lvm_use_thinpool

Adds the lvm.use_thinpool configuration key, a Boolean that defaults to true. When set to false, LXD creates plain logical volumes for storage entities instead of using an LVM thin pool.

storage_rsync_bwlimit

When rsync has to be invoked to transfer storage entities setting rsync.bwlimit places an upper limit on the amount of socket I/O allowed.

network_vxlan_interface

This introduces a new tunnel.NAME.interface option for networks.

This key control what host network interface is used for a VXLAN tunnel.

storage_btrfs_mount_options

This introduces the btrfs.mount_options property for Btrfs storage pools.

This key controls what mount options will be used for the Btrfs storage pool.

entity_description

This adds descriptions to entities like instances, snapshots, networks, storage pools and volumes.

image_force_refresh

This allows forcing a refresh for an existing image.

storage_lvm_lv_resizing

This introduces the ability to resize logical volumes by setting the size property in the instance root disk device.

id_map_base

This introduces a new security.idmap.base allowing the user to skip the map auto-selection process for isolated containers and specify what host UID/GID to use as the base.

container_push_target

This adds the target field to POST /1.0/instances/<name> which can be used to have the source LXD host connect to the target during migration.

network_vlan_physical

Allows use of vlan property with physical network devices.

When set, this will instruct LXD to attach to the specified VLAN on the parent interface. LXD will look for an existing interface for that parent and VLAN on the host. If one can’t be found it will create one itself. Then, LXD will directly attach this interface to the container.

storage_images_delete

This enabled the storage API to delete storage volumes for images from a specific storage pool.

container_edit_metadata

This adds support for editing an instance metadata.yaml and related templates via API, by accessing URLs under /1.0/instances/<name>/metadata. It can be used to edit an instance before publishing an image from it.

container_snapshot_stateful_migration

This enables migrating stateful container snapshots to new containers.

storage_driver_ceph

This adds a Ceph storage driver.

storage_ceph_user_name

This adds the ability to specify the Ceph user.

resource_limits

This adds the instance_type field to the container creation request. Its value is expanded to LXD resource limits.

storage_volatile_initial_source

This records the actual source passed to LXD during storage pool creation.

storage_ceph_force_osd_reuse

This introduces the ceph.osd.force_reuse property for the Ceph storage driver. When set to true LXD will reuse an OSD storage pool that is already in use by another LXD instance.

storage_block_filesystem_btrfs

This adds support for Btrfs as a storage volume file system, in addition to ext4 and xfs.

resources

This adds support for querying a LXD daemon for the system resources it has available.

kernel_limits

This adds support for setting process limits such as maximum number of open files for the container via nofile. The format is limits.kernel.[limit name].

storage_api_volume_rename

This adds support for renaming custom storage volumes.

network_sriov

This adds support for SR-IOV enabled network devices.

console

This adds support to interact with the container console device and console log.

restrict_devlxd

A new security.devlxd container configuration key was introduced. The key controls whether the /dev/lxd interface is made available to the instance. If set to false, this effectively prevents the container from interacting with the LXD daemon.

migration_pre_copy

This adds support for optimized memory transfer during live migration.

infiniband

This adds support to use InfiniBand network devices.

devlxd_events

This adds a WebSocket API to the devlxd socket.

When connecting to /1.0/events over the devlxd socket, you will now be getting a stream of events over WebSocket.

proxy

This adds a new proxy device type to containers, allowing forwarding of connections between the host and container.

network_dhcp_gateway