README.md

NAME

Net::Async::WebService::lxd - REST client (asynchronous) for lxd Linux containers

SYNOPSIS

use IO::Async::Loop;
my $loop = IO::Async::Loop->new;

use Net::Async::WebService::lxd;
my $lxd = Net::Async::WebService::lxd->new( loop            => $loop,
                                            endpoint        => 'https://192.168.0.50:8443',
                                            SSL_cert_file   => "t/client.crt",
                                            SSL_key_file    => "t/client.key",
                                            SSL_fingerprint => 'sha1$92:DD:63:F8:99:C4:5F:82:59:52:82:A9:09:C8:57:F0:67:56:B0:1B',
                                            );
$lxd->create_instance(
         body => {
             architecture => 'x86_64',
             profiles     => [ 'default'  ],
             name         => 'test1',
             source       => { type        => 'image',
                               fingerprint => '6dc6aa7c8c00' },  # image already exists in image store
             config       => {},
         } )->get;                                               # wait for it
# container is still stopped
$lxd->instance_state( name => 'test1',
         body => {
             action   => "start",
             force    => JSON::false,
             stateful => JSON::false,
             timeout  => 30,
         } )->get;                                               # wait for it

INTERFACE

Constructor

The constructor returns a handle to one LXD server. It's address is specified via an endpoint parameter, be it of an HTTPS or of a UNIX socket kind.

If you are working with a non-default LXD project in mind, then you should also provide that project's name with the project parameter. Background operation polling will make use of that. Note, that when invoking any of the methods here, you will still have to specify that project, unless it is the default one, of course.

As we are operating under an IO::Async regime here, the handle also needs a loop parameter to the central event loop. The handle will also regularily poll autonomously the server which operations are still running or have completed. The optional parameter polling_time controls how often that will occur; it will default to 1 sec, if not provided.

As LXD can be accessed remotely only via HTTPS, TLS (SSL) parameters must be provided. These will be forwarded directly to IO::Socket::SSL. But, specifically, one should consider to provide:

• client certificate, via a proper subset of SSL_cert_file, SSL_key_file, SSL_cert and SSL_key. (Look at the "HINTS" section to generate such a certificate for LXD.)
• server fingerprint, via SSL_fingerprint (Look at the "HINTS" section how to figure this out.)

Methods

All methods below are automatically generated from the LXD REST API Spec. They should work with API version 1.0.

Let's dissect method invocations with this example:

my $f = $lxd->instance_state( name => 'test1' );
my $r = $f->get;

• All invocations return a Future. Thus they can be combined, sequenced, run in "parallel", etc. If you need to wait for a definite result, then you will block the flow with ->get.

  Polling is done behind the scenes and will watch for all operations which either succeeded or failed. Those will mark the associated future as done or failed. Normally, you will never need to use the methods for 'Operations' yourself; they are still offered as fallback.

• The result of each fully completed invocation is either

  • the string success, or
  • a Perl HASH ref which reflects the JSON data sent from the LXD server. Note, that Booleans have to be treated special, by using JSON::false and JSON::true. Otherwise, they follow exactly the structure in the specification.
  • or a HASH ref with keys stdin and stdout if this is a result of the execute_in_instance method.

• If an operation failed, then the associated future will be failed, together with the reason of the failure from the server. If you do not cater with that, then this will - as usual with IO::Async - raise an exception, with the failure as string.

• Methods named like the type of server object (e.g. cluster, certificate, image) are normally "getter/setter" methods. The getter obviously returns the state of the object. The method becomes a setter, if the additional body field together with a Perl HASH ref is passed:

    my $f = $lxd->instance_state( name => 'test1',
                                  body => {
                                    action   => "start",
                                    force    => JSON::false,
                                    stateful => JSON::false,
                                    timeout  => 30,
                                  } );
  

  That HASH ref also follows the structure outlined in the specification for that particular endpoint.

  How a specific object is addressed, is detailed in each method below; usually you provide a name, id, fingerprint, or similar. You may also have to provide a project, if not being the default project.

• Methods named like a plural of type of server object (e.g. certificates) normally return a list of identifiers for such objects.

• Many methods request changes in the LXD server. The names are taken from the specification, but are adapted to better reflect what is intended:

  • Methods which change the state of the remote object usually are called modify_something.
  • Methods which add a new object to a collection are usually called add_something, or create_something, depending on how it sounds better.
  • Methods which remove an object from a collection are usually called delete_something.

Certificates

• add_certificate

  Adds a certificate to the trust store. In this mode, the `password` property is always ignored.

  • body: certificate, required

      description: CertificatesPost represents the fields of a new LXD certificate
      properties:
        certificate:
          description: 'The certificate itself, as PEM encoded X509'
          example: X509 PEM certificate
          type: string
        name:
          description: Name associated with the certificate
          example: castiana
          type: string
        password:
          description: Server trust password (used to add an untrusted client)
          example: blah
          type: string
        projects:
          description: List of allowed projects (applies when restricted)
          example:
            - default
            - foo
            - bar
          items:
            type: string
          type: array
        restricted:
          description: Whether to limit the certificate to listed projects
          example: true
          type: boolean
        token:
          description: Whether to create a certificate add token
          example: true
          type: boolean
        type:
          description: Usage type for the certificate (only client currently)
          example: client
          type: string
      type: object
    

• add_certificate_untrusted

  Adds a certificate to the trust store as an untrusted user. In this mode, the `password` property must be set to the correct value.

  The `certificate` field can be omitted in which case the TLS client certificate in use for the connection will be retrieved and added to the trust store.

  The `?public` part of the URL isn't required, it's simply used to separate the two behaviors of this endpoint.

  • body: certificate, required

      description: CertificatesPost represents the fields of a new LXD certificate
      properties:
        certificate:
          description: 'The certificate itself, as PEM encoded X509'
          example: X509 PEM certificate
          type: string
        name:
          description: Name associated with the certificate
          example: castiana
          type: string
        password:
          description: Server trust password (used to add an untrusted client)
          example: blah
          type: string
        projects:
          description: List of allowed projects (applies when restricted)
          example:
            - default
            - foo
            - bar
          items:
            type: string
          type: array
        restricted:
          description: Whether to limit the certificate to listed projects
          example: true
          type: boolean
        token:
          description: Whether to create a certificate add token
          example: true
          type: boolean
        type:
          description: Usage type for the certificate (only client currently)
          example: client
          type: string
      type: object
    

• certificate

  Gets a specific certificate entry from the trust store.

  Updates the entire certificate configuration.

  • fingerprint: string, required

  • body: certificate, required

      description: CertificatePut represents the modifiable fields of a LXD certificate
      properties:
        certificate:
          description: 'The certificate itself, as PEM encoded X509'
          example: X509 PEM certificate
          type: string
        name:
          description: Name associated with the certificate
          example: castiana
          type: string
        projects:
          description: List of allowed projects (applies when restricted)
          example:
            - default
            - foo
            - bar
          items:
            type: string
          type: array
        restricted:
          description: Whether to limit the certificate to listed projects
          example: true
          type: boolean
        type:
          description: Usage type for the certificate (only client currently)
          example: client
          type: string
      type: object
    

• certificates

  Returns a list of trusted certificates (URLs).

• certificates_recursion1

  Returns a list of trusted certificates (structs).

• delete_certificate

  Removes the certificate from the trust store.

  • fingerprint: string, required

• modify_certificate

  Updates a subset of the certificate configuration.

  • fingerprint: string, required

  • body: certificate, required

      description: CertificatePut represents the modifiable fields of a LXD certificate
      properties:
        certificate:
          description: 'The certificate itself, as PEM encoded X509'
          example: X509 PEM certificate
          type: string
        name:
          description: Name associated with the certificate
          example: castiana
          type: string
        projects:
          description: List of allowed projects (applies when restricted)
          example:
            - default
            - foo
            - bar
          items:
            type: string
          type: array
        restricted:
          description: Whether to limit the certificate to listed projects
          example: true
          type: boolean
        type:
          description: Usage type for the certificate (only client currently)
          example: client
          type: string
      type: object
    

Cluster

• add_cluster_member

  Requests a join token to add a cluster member.

  • body: cluster, required

      properties:
        server_name:
          description: The name of the new cluster member
          example: lxd02
          type: string
      title: ClusterMembersPost represents the fields required to request a join token to add a member to the cluster.
      type: object
    

• cluster

  Gets the current cluster configuration.

  Updates the entire cluster configuration.

  • body: cluster, required

      description: |-
        ClusterPut represents the fields required to bootstrap or join a LXD
        cluster.
      properties:
        cluster_address:
          description: The address of the cluster you wish to join
          example: 10.0.0.1:8443
          type: string
        cluster_certificate:
          description: The expected certificate (X509 PEM encoded) for the cluster
          example: X509 PEM certificate
          type: string
        cluster_password:
          description: The trust password of the cluster you're trying to join
          example: blah
          type: string
        enabled:
          description: Whether clustering is enabled
          example: true
          type: boolean
        member_config:
          description: List of member configuration keys (used during join)
          example: []
          items:
            $ref: '#/definitions/ClusterMemberConfigKey'
          type: array
        server_address:
          description: The local address to use for cluster communication
          example: 10.0.0.2:8443
          type: string
        server_name:
          description: Name of the cluster member answering the request
          example: lxd01
          type: string
      type: object
    

• cluster_member

  Gets a specific cluster member.

  Updates the entire cluster member configuration.

  • name: string, required

  • body: cluster, required

      description: ClusterMemberPut represents the the modifiable fields of a LXD cluster member
      properties:
        config:
          additionalProperties:
            type: string
          description: Additional configuration information
          example:
            scheduler.instance: all
          type: object
        description:
          description: Cluster member description
          example: AMD Epyc 32c/64t
          type: string
        failure_domain:
          description: Name of the failure domain for this cluster member
          example: rack1
          type: string
        groups:
          description: List of cluster groups this member belongs to
          example:
            - group1
            - group2
          items:
            type: string
          type: array
        roles:
          description: List of roles held by this cluster member
          example:
            - database
          items:
            type: string
          type: array
      type: object
    

• cluster_members

  Returns a list of cluster members (URLs).

• cluster_members_recursion1

  Returns a list of cluster members (structs).

• clustering_update_cert

  Replaces existing cluster certificate and reloads LXD on each cluster member.

  • body: cluster, required

      description: ClusterCertificatePut represents the certificate and key pair for all members in a LXD Cluster
      properties:
        cluster_certificate:
          description: The new certificate (X509 PEM encoded) for the cluster
          example: X509 PEM certificate
          type: string
        cluster_certificate_key:
          description: The new certificate key (X509 PEM encoded) for the cluster
          example: X509 PEM certificate key
          type: string
      type: object
    

• create_cluster_group

  Creates a new cluster group.

  • body: cluster, required

      properties:
        description:
          description: The description of the cluster group
          example: amd64 servers
          type: string
        members:
          description: List of members in this group
          example:
            - node1
            - node3
          items:
            type: string
          type: array
        name:
          description: The new name of the cluster group
          example: group1
          type: string
      title: ClusterGroupsPost represents the fields available for a new cluster group.
      type: object
    

• delete_cluster_member

  Removes the member from the cluster.

  • name: string, required

• modify_cluster_member

  Updates a subset of the cluster member configuration.

  • name: string, required

  • body: cluster, required

      description: ClusterMemberPut represents the the modifiable fields of a LXD cluster member
      properties:
        config:
          additionalProperties:
            type: string
          description: Additional configuration information
          example:
            scheduler.instance: all
          type: object
        description:
          description: Cluster member description
          example: AMD Epyc 32c/64t
          type: string
        failure_domain:
          description: Name of the failure domain for this cluster member
          example: rack1
          type: string
        groups:
          description: List of cluster groups this member belongs to
          example:
            - group1
            - group2
          items:
            type: string
          type: array
        roles:
          description: List of roles held by this cluster member
          example:
            - database
          items:
            type: string
          type: array
      type: object
    

• rename_cluster_member

  Renames an existing cluster member.

  • name: string, required

  • body: cluster, required

      properties:
        server_name:
          description: The new name of the cluster member
          example: lxd02
          type: string
      title: ClusterMemberPost represents the fields required to rename a LXD node.
      type: object
    

• restore_cluster_member_state

  Evacuates or restores a cluster member.

  • name: string, required

  • body: cluster, required

      properties:
        action:
          description: The action to be performed. Valid actions are "evacuate" and "restore".
          example: evacuate
          type: string
      title: ClusterMemberStatePost represents the fields required to evacuate a cluster member.
      type: object
    

Cluster Groups

• cluster_group

  Gets a specific cluster group.

  Updates the entire cluster group configuration.

  • name: string, required

  • body: cluster group, required

      properties:
        description:
          description: The description of the cluster group
          example: amd64 servers
          type: string
        members:
          description: List of members in this group
          example:
            - node1
            - node3
          items:
            type: string
          type: array
      title: ClusterGroupPut represents the modifiable fields of a cluster group.
      type: object
    

• cluster_groups

  Returns a list of cluster groups (URLs).

• cluster_groups_recursion1

  Returns a list of cluster groups (structs).

• delete_cluster_group

  Removes the cluster group.

  • name: string, required

• modify_cluster_group

  Updates the cluster group configuration.

  • name: string, required

  • body: cluster group, required

      properties:
        description:
          description: The description of the cluster group
          example: amd64 servers
          type: string
        members:
          description: List of members in this group
          example:
            - node1
            - node3
          items:
            type: string
          type: array
      title: ClusterGroupPut represents the modifiable fields of a cluster group.
      type: object
    

• rename_cluster_group

  Renames an existing cluster group.

  • name: string, required

  • body: name, required

      properties:
        name:
          description: The new name of the cluster group
          example: group1
          type: string
      title: ClusterGroupPost represents the fields required to rename a cluster group.
      type: object
    

Images

• add_images_alias

  Creates a new image alias.

  • project: string, optional

  • body: image alias, required

      description: ImageAliasesPost represents a new LXD image alias
      properties:
        description:
          description: Alias description
          example: Our preferred Ubuntu image
          type: string
        name:
          description: Alias name
          example: ubuntu-20.04
          type: string
        target:
          description: Target fingerprint for the alias
          example: 06b86454720d36b20f94e31c6812e05ec51c1b568cf3a8abd273769d213394bb
          type: string
        type:
          description: Alias type (container or virtual-machine)
          example: container
          type: string
      type: object
    

• create_image

  Adds a new image to the image store.

  • project: string, optional

  • body: image, optional

      description: ImagesPost represents the fields available for a new LXD image
      properties:
        aliases:
          description: Aliases to add to the image
          example:
            - name: foo
            - name: bar
          items:
            $ref: '#/definitions/ImageAlias'
          type: array
        auto_update:
          description: Whether the image should auto-update when a new build is available
          example: true
          type: boolean
        compression_algorithm:
          description: Compression algorithm to use when turning an instance into an image
          example: gzip
          type: string
        expires_at:
          description: When the image becomes obsolete
          example: 2025-03-23T20:00:00-04:00
          format: date-time
          type: string
        filename:
          description: Original filename of the image
          example: lxd.tar.xz
          type: string
        profiles:
          description: List of profiles to use when creating from this image (if none provided by user)
          example:
            - default
          items:
            type: string
          type: array
        properties:
          additionalProperties:
            type: string
          description: Descriptive properties
          example:
            os: Ubuntu
            release: focal
            variant: cloud
          type: object
        public:
          description: Whether the image is available to unauthenticated users
          example: false
          type: boolean
        source:
          $ref: '#/definitions/ImagesPostSource'
      type: object
    

  • body: raw_image, optionalsee Spec

• delete_image

  Removes the image from the image store.

  • fingerprint: string, required
  • project: string, optional

• delete_image_alias

  Deletes a specific image alias.

  • name: string, required
  • project: string, optional

• image

  Gets a specific image.

  Updates the entire image definition.

  • fingerprint: string, required

  • project: string, optional

  • body: image, required

      description: ImagePut represents the modifiable fields of a LXD image
      properties:
        auto_update:
          description: Whether the image should auto-update when a new build is available
          example: true
          type: boolean
        expires_at:
          description: When the image becomes obsolete
          example: 2025-03-23T20:00:00-04:00
          format: date-time
          type: string
        profiles:
          description: List of profiles to use when creating from this image (if none provided by user)
          example:
            - default
          items:
            type: string
          type: array
        properties:
          additionalProperties:
            type: string
          description: Descriptive properties
          example:
            os: Ubuntu
            release: focal
            variant: cloud
          type: object
        public:
          description: Whether the image is available to unauthenticated users
          example: false
          type: boolean
      type: object
    

• image_alias

  Gets a specific image alias.

  Updates the entire image alias configuration.

  • name: string, required

  • project: string, optional

  • body: image alias, required

      description: ImageAliasesEntryPut represents the modifiable fields of a LXD image alias
      properties:
        description:
          description: Alias description
          example: Our preferred Ubuntu image
          type: string
        target:
          description: Target fingerprint for the alias
          example: 06b86454720d36b20f94e31c6812e05ec51c1b568cf3a8abd273769d213394bb
          type: string
      type: object
    

• image_alias_untrusted

  Gets a specific public image alias. This untrusted endpoint only works for aliases pointing to public images.

  • name: string, required
  • project: string, optional

• image_export

  Download the raw image file(s) from the server. If the image is in split format, a multipart http transfer occurs.

  • fingerprint: string, required
  • project: string, optional

• image_export_untrusted

  Download the raw image file(s) of a public image from the server. If the image is in split format, a multipart http transfer occurs.

  • fingerprint: string, required
  • project: string, optional
  • secret: string, optional

• image_untrusted

  Gets a specific public image.

  • fingerprint: string, required
  • project: string, optional
  • secret: string, optional

• images

  Returns a list of images (URLs).

  • filter: string, optional
  • project: string, optional

• images_aliases

  Returns a list of image aliases (URLs).

  • project: string, optional

• images_aliases_recursion1

  Returns a list of image aliases (structs).

  • project: string, optional

• images_recursion1

  Returns a list of images (structs).

  • filter: string, optional
  • project: string, optional

• images_recursion1_untrusted

  Returns a list of publicly available images (structs).

  • filter: string, optional
  • project: string, optional

• images_untrusted

  Returns a list of publicly available images (URLs).

  • filter: string, optional
  • project: string, optional

• initiate_image_upload

  This generates a background operation including a secret one time key in its metadata which can be used to fetch this image from an untrusted client.

  • fingerprint: string, required
  • project: string, optional

• modify_image

  Updates a subset of the image definition.

  • fingerprint: string, required

  • project: string, optional

  • body: image, required

      description: ImagePut represents the modifiable fields of a LXD image
      properties:
        auto_update:
          description: Whether the image should auto-update when a new build is available
          example: true
          type: boolean
        expires_at:
          description: When the image becomes obsolete
          example: 2025-03-23T20:00:00-04:00
          format: date-time
          type: string
        profiles:
          description: List of profiles to use when creating from this image (if none provided by user)
          example:
            - default
          items:
            type: string
          type: array
        properties:
          additionalProperties:
            type: string
          description: Descriptive properties
          example:
            os: Ubuntu
            release: focal
            variant: cloud
          type: object
        public:
          description: Whether the image is available to unauthenticated users
          example: false
          type: boolean
      type: object
    

• modify_images_alias

  Updates a subset of the image alias configuration.

  • name: string, required

  • project: string, optional

  • body: image alias, required

      description: ImageAliasesEntryPut represents the modifiable fields of a LXD image alias
      properties:
        description:
          description: Alias description
          example: Our preferred Ubuntu image
          type: string
        target:
          description: Target fingerprint for the alias
          example: 06b86454720d36b20f94e31c6812e05ec51c1b568cf3a8abd273769d213394bb
          type: string
      type: object
    

• push_image_untrusted

  Pushes the data to the target image server. This is meant for LXD to LXD communication where a new image entry is prepared on the target server and the source server is provided that URL and a secret token to push the image content over.

  • project: string, optional

  • body: image, required

      description: ImagesPost represents the fields available for a new LXD image
      properties:
        aliases:
          description: Aliases to add to the image
          example:
            - name: foo
            - name: bar
          items:
            $ref: '#/definitions/ImageAlias'
          type: array
        auto_update:
          description: Whether the image should auto-update when a new build is available
          example: true
          type: boolean
        compression_algorithm:
          description: Compression algorithm to use when turning an instance into an image
          example: gzip
          type: string
        expires_at:
          description: When the image becomes obsolete
          example: 2025-03-23T20:00:00-04:00
          format: date-time
          type: string
        filename:
          description: Original filename of the image
          example: lxd.tar.xz
          type: string
        profiles:
          description: List of profiles to use when creating from this image (if none provided by user)
          example:
            - default
          items:
            type: string
          type: array
        properties:
          additionalProperties:
            type: string
          description: Descriptive properties
          example:
            os: Ubuntu
            release: focal
            variant: cloud
          type: object
        public:
          description: Whether the image is available to unauthenticated users
          example: false
          type: boolean
        source:
          $ref: '#/definitions/ImagesPostSource'
      type: object
    

• push_images_export

  Gets LXD to connect to a remote server and push the image to it.

  • fingerprint: string, required

  • project: string, optional

  • body: image, required

      description: ImageExportPost represents the fields required to export a LXD image
      properties:
        aliases:
          description: List of aliases to set on the image
          items:
            $ref: '#/definitions/ImageAlias'
          type: array
        certificate:
          description: Remote server certificate
          example: X509 PEM certificate
          type: string
        secret:
          description: Image receive secret
          example: RANDOM-STRING
          type: string
        target:
          description: Target server URL
          example: https://1.2.3.4:8443
          type: string
      type: object
    

• rename_images_alias

  Renames an existing image alias.

  • name: string, required

  • project: string, optional

  • body: image alias, required

      description: ImageAliasesEntryPost represents the required fields to rename a LXD image alias
      properties:
        name:
          description: Alias name
          example: ubuntu-20.04
          type: string
      type: object
    

• update_images_refresh

  This causes LXD to check the image source server for an updated version of the image and if available to refresh the local copy with the new version.

  • fingerprint: string, required
  • project: string, optional

Instances

• connect_instance_console

  Connects to the console of an instance.

  The returned operation metadata will contain two websockets, one for data and one for control.

  • name: string, required

  • project: string, optional

  • body: console, optional

      properties:
        height:
          description: Console height in rows (console type only)
          example: 24
          format: int64
          type: integer
        type:
          description: Type of console to attach to (console or vga)
          example: console
          type: string
        width:
          description: Console width in columns (console type only)
          example: 80
          format: int64
          type: integer
      title: InstanceConsolePost represents a LXD instance console request.
      type: object
    

• create_instance

  Creates a new instance on LXD. Depending on the source, this can create an instance from an existing local image, remote image, existing local instance or snapshot, remote migration stream or backup file.

  • project: string, optional

  • target: string, optional

  • body: instance, optional

      properties:
        architecture:
          description: Architecture name
          example: x86_64
          type: string
        config:
          additionalProperties:
            type: string
          description: Instance configuration (see doc/instances.md)
          example:
            security.nesting: true
          type: object
        description:
          description: Instance description
          example: My test instance
          type: string
        devices:
          additionalProperties:
            additionalProperties:
              type: string
            type: object
          description: Instance devices (see doc/instances.md)
          example:
            root:
              path: /
              pool: default
              type: disk
          type: object
        ephemeral:
          description: Whether the instance is ephemeral (deleted on shutdown)
          example: false
          type: boolean
        instance_type:
          description: 'Cloud instance type (AWS, GCP, Azure, ...) to emulate with limits'
          example: t1.micro
          type: string
        name:
          description: Instance name
          example: foo
          type: string
        profiles:
          description: List of profiles applied to the instance
          example:
            - default
          items:
            type: string
          type: array
        restore:
          description: 'If set, instance will be restored to the provided snapshot name'
          example: snap0
          type: string
        source:
          $ref: '#/definitions/InstanceSource'
        stateful:
          description: Whether the instance currently has saved state on disk
          example: false
          type: boolean
        type:
          $ref: '#/definitions/InstanceType'
      title: InstancesPost represents the fields available for a new LXD instance.
      type: object
    

  • body: raw_backup, optionalsee Spec

• create_instance_backup

  Creates a new backup.

  • name: string, required

  • project: string, optional

  • body: backup, optional

      properties:
        compression_algorithm:
          description: What compression algorithm to use
          example: gzip
          type: string
        container_only:
          description: 'Whether to ignore snapshots (deprecated, use instance_only)'
          example: false
          type: boolean
        expires_at:
          description: When the backup expires (gets auto-deleted)
          example: 2021-03-23T17:38:37.753398689-04:00
          format: date-time
          type: string
        instance_only:
          description: Whether to ignore snapshots
          example: false
          type: boolean
        name:
          description: Backup name
          example: backup0
          type: string
        optimized_storage:
          description: Whether to use a pool-optimized binary format (instead of plain tarball)
          example: true
          type: boolean
      title: InstanceBackupsPost represents the fields available for a new LXD instance backup.
      type: object
    

• create_instance_file

  Creates a new file in the instance.

  • name: string, required
  • path: string, optional
  • project: string, optional
  • body: raw_file, optionalsee Spec

• create_instance_metadata_template

  Creates a new image template file for the instance.

  • name: string, required
  • path: string, optional
  • project: string, optional
  • body: raw_file, optionalsee Spec

• create_instance_snapshot

  Creates a new snapshot.

  • name: string, required

  • project: string, optional

  • body: snapshot, optional

      properties:
        expires_at:
          description: When the snapshot expires (gets auto-deleted)
          example: 2021-03-23T17:38:37.753398689-04:00
          format: date-time
          type: string
        name:
          description: Snapshot name
          example: snap0
          type: string
        stateful:
          description: Whether the snapshot should include runtime state
          example: false
          type: boolean
      title: InstanceSnapshotsPost represents the fields available for a new LXD instance snapshot.
      type: object
    

• delete_instance

  Deletes a specific instance.

  This also deletes anything owned by the instance such as snapshots and backups.

  • name: string, required
  • project: string, optional

• delete_instance_backup

  Deletes the instance backup.

  • backup: string, required
  • name: string, required
  • project: string, optional

• delete_instance_console

  Clears the console log buffer.

  • name: string, required
  • project: string, optional

• delete_instance_files

  Removes the file.

  • name: string, required
  • path: string, optional
  • project: string, optional

• delete_instance_log

  Removes the log file.

  • filename: string, required
  • name: string, required
  • project: string, optional

• delete_instance_metadata_templates

  Removes the template file.

  • name: string, required
  • path: string, optional
  • project: string, optional

• delete_instance_snapshot

  Deletes the instance snapshot.

  • name: string, required
  • snapshot: string, required
  • project: string, optional

• execute_in_instance

  Executes a command inside an instance.

  The returned operation metadata will contain either 2 or 4 websockets. In non-interactive mode, you'll get one websocket for each of stdin, stdout and stderr. In interactive mode, a single bi-directional websocket is used for stdin and stdout/stderr.

  An additional "control" socket is always added on top which can be used for out of band communication with LXD. This allows sending signals and window sizing information through.

  • name: string, required

  • project: string, optional

  • body: exec, optional

      properties:
        command:
          description: Command and its arguments
          example:
            - bash
          items:
            type: string
          type: array
        cwd:
          description: Current working directory for the command
          example: /home/foo/
          type: string
        environment:
          additionalProperties:
            type: string
          description: Additional environment to pass to the command
          example:
            FOO: BAR
          type: object
        group:
          description: GID of the user to spawn the command as
          example: 1000
          format: uint32
          type: integer
        height:
          description: Terminal height in rows (for interactive)
          example: 24
          format: int64
          type: integer
        interactive:
          description: Whether the command is to be spawned in interactive mode (singled PTY instead of 3 PIPEs)
          example: true
          type: boolean
        record-output:
          description: Whether to capture the output for later download (requires non-interactive)
          type: boolean
        user:
          description: UID of the user to spawn the command as
          example: 1000
          format: uint32
          type: integer
        wait-for-websocket:
          description: Whether to wait for all websockets to be connected before spawning the command
          example: true
          type: boolean
        width:
          description: Terminal width in characters (for interactive)
          example: 80
          format: int64
          type: integer
      title: InstanceExecPost represents a LXD instance exec request.
      type: object
    

• instance

  Gets a specific instance (basic struct).

  Updates the instance configuration or trigger a snapshot restore.

  • name: string, required

  • project: string, optional

  • body: instance, optional

      properties:
        architecture:
          description: Architecture name
          example: x86_64
          type: string
        config:
          additionalProperties:
            type: string
          description: Instance configuration (see doc/instances.md)
          example:
            security.nesting: true
          type: object
        description:
          description: Instance description
          example: My test instance
          type: string
        devices:
          additionalProperties:
            additionalProperties:
              type: string
            type: object
          description: Instance devices (see doc/instances.md)
          example:
            root:
              path: /
              pool: default
              type: disk
          type: object
        ephemeral:
          description: Whether the instance is ephemeral (deleted on shutdown)
          example: false
          type: boolean
        profiles:
          description: List of profiles applied to the instance
          example:
            - default
          items:
            type: string
          type: array
        restore:
          description: 'If set, instance will be restored to the provided snapshot name'
          example: snap0
          type: string
        stateful:
          description: Whether the instance currently has saved state on disk
          example: false
          type: boolean
      title: InstancePut represents the modifiable fields of a LXD instance.
      type: object
    

• instance_backup

  Gets a specific instance backup.

  • backup: string, required
  • name: string, required
  • project: string, optional

• instance_backup_export

  Download the raw backup file(s) from the server.

  • backup: string, required
  • name: string, required
  • project: string, optional

• instance_backups

  Returns a list of instance backups (URLs).

  • name: string, required
  • project: string, optional

• instance_backups_recursion1

  Returns a list of instance backups (structs).

  • name: string, required
  • project: string, optional

• instance_console

  Gets the console log for the instance.

  • name: string, required
  • project: string, optional

• instance_files

  Gets the file content. If it's a directory, a json list of files will be returned instead.

  • name: string, required
  • path: string, optional
  • project: string, optional

• instance_log

  Gets the log file.

  • filename: string, required
  • name: string, required
  • project: string, optional

• instance_logs

  Returns a list of log files (URLs).

  • name: string, required
  • project: string, optional

• instance_metadata

  Gets the image metadata for the instance.

  Updates the instance image metadata.

  • name: string, required

  • project: string, optional

  • body: metadata, required

      description: ImageMetadata represents LXD image metadata (used in image tarball)
      properties:
        architecture:
          description: Architecture name
          example: x86_64
          type: string
        creation_date:
          description: Image creation data (as UNIX epoch)
          example: 1620655439
          format: int64
          type: integer
        expiry_date:
          description: Image expiry data (as UNIX epoch)
          example: 1620685757
          format: int64
          type: integer
        properties:
          additionalProperties:
            type: string
          description: Descriptive properties
          example:
            os: Ubuntu
            release: focal
            variant: cloud
          type: object
        templates:
          additionalProperties:
            $ref: '#/definitions/ImageMetadataTemplate'
          description: Template for files in the image
          type: object
      type: object
    

• instance_metadata_templates

  If no path specified, returns a list of template file names. If a path is specified, returns the file content.

  • name: string, required
  • path: string, optional
  • project: string, optional

• instance_recursion1

  Gets a specific instance (full struct).

  recursion=1 also includes information about state, snapshots and backups.

  • name: string, required
  • project: string, optional

• instance_snapshot

  Gets a specific instance snapshot.

  Updates the snapshot config.

  • name: string, required

  • snapshot: string, required

  • project: string, optional

  • body: snapshot, optional

      properties:
        expires_at:
          description: When the snapshot expires (gets auto-deleted)
          example: 2021-03-23T17:38:37.753398689-04:00
          format: date-time
          type: string
      title: InstanceSnapshotPut represents the modifiable fields of a LXD instance snapshot.
      type: object
    

• instance_snapshots

  Returns a list of instance snapshots (URLs).

  • name: string, required
  • project: string, optional

• instance_snapshots_recursion1

  Returns a list of instance snapshots (structs).

  • name: string, required
  • project: string, optional

• instance_state

  Gets the runtime state of the instance.

  This is a reasonably expensive call as it causes code to be run inside of the instance to retrieve the resource usage and network information.

  Changes the running state of the instance.

  • name: string, required

  • project: string, optional

  • body: state, optional

      properties:
        action:
          description: 'State change action (start, stop, restart, freeze, unfreeze)'
          example: start
          type: string
        force:
          description: Whether to force the action (for stop and restart)
          example: false
          type: boolean
        stateful:
          description: Whether to store the runtime state (for stop)
          example: false
          type: boolean
        timeout:
          description: How long to wait (in s) before giving up (when force isn't set)
          example: 30
          format: int64
          type: integer
      title: InstanceStatePut represents the modifiable fields of a LXD instance's state.
      type: object
    

• instances

  Returns a list of instances (URLs).

  Changes the running state of all instances.

  • all-projects: boolean, optional

  • filter: string, optional

  • project: string, optional

  • body: state, optional

      properties:
        state:
          $ref: '#/definitions/InstanceStatePut'
      title: InstancesPut represents the fields available for a mass update.
      type: object
    

• instances_recursion1

  Returns a list of instances (basic structs).

  • all-projects: boolean, optional
  • filter: string, optional
  • project: string, optional

• instances_recursion2

  Returns a list of instances (full structs).

  The main difference between recursion=1 and recursion=2 is that the latter also includes state and snapshot information allowing for a single API call to return everything needed by most clients.

  • all-projects: boolean, optional
  • filter: string, optional
  • project: string, optional

• migrate_instance

  Renames, moves an instance between pools or migrates an instance to another server.

  The returned operation metadata will vary based on what's requested. For rename or move within the same server, this is a simple background operation with progress data. For migration, in the push case, this will similarly be a background operation with progress data, for the pull case, it will be a websocket operation with a number of secrets to be passed to the target server.

  • name: string, required

  • project: string, optional

  • body: migration, optional

      properties:
        container_only:
          description: 'Whether snapshots should be discarded (migration only, deprecated, use instance_only)'
          example: false
          type: boolean
        instance_only:
          description: Whether snapshots should be discarded (migration only)
          example: false
          type: boolean
        live:
          description: Whether to perform a live migration (migration only)
          example: false
          type: boolean
        migration:
          description: Whether the instance is being migrated to another server
          example: false
          type: boolean
        name:
          description: New name for the instance
          example: bar
          type: string
        pool:
          description: Target pool for local cross-pool move
          example: baz
          type: string
        project:
          description: Target project for local cross-project move
          example: foo
          type: string
        target:
          $ref: '#/definitions/InstancePostTarget'
      title: InstancePost represents the fields required to rename/move a LXD instance.
      type: object
    

• migrate_instance_snapshot

  Renames or migrates an instance snapshot to another server.

  The returned operation metadata will vary based on what's requested. For rename or move within the same server, this is a simple background operation with progress data. For migration, in the push case, this will similarly be a background operation with progress data, for the pull case, it will be a websocket operation with a number of secrets to be passed to the target server.

  • name: string, required

  • snapshot: string, required

  • project: string, optional

  • body: snapshot, optional

      properties:
        live:
          description: Whether to perform a live migration (requires migration)
          example: false
          type: boolean
        migration:
          description: Whether this is a migration request
          example: false
          type: boolean
        name:
          description: New name for the snapshot
          example: foo
          type: string
        target:
          $ref: '#/definitions/InstancePostTarget'
      title: InstanceSnapshotPost represents the fields required to rename/move a LXD instance snapshot.
      type: object
    

• modify_instance

  Updates a subset of the instance configuration

  • name: string, required

  • project: string, optional

  • body: instance, optional

      properties:
        architecture:
          description: Architecture name
          example: x86_64
          type: string
        config:
          additionalProperties:
            type: string
          description: Instance configuration (see doc/instances.md)
          example:
            security.nesting: true
          type: object
        description:
          description: Instance description
          example: My test instance
          type: string
        devices:
          additionalProperties:
            additionalProperties:
              type: string
            type: object
          description: Instance devices (see doc/instances.md)
          example:
            root:
              path: /
              pool: default
              type: disk
          type: object
        ephemeral:
          description: Whether the instance is ephemeral (deleted on shutdown)
          example: false
          type: boolean
        profiles:
          description: List of profiles applied to the instance
          example:
            - default
          items:
            type: string
          type: array
        restore:
          description: 'If set, instance will be restored to the provided snapshot name'
          example: snap0
          type: string
        stateful:
          description: Whether the instance currently has saved state on disk
          example: false
          type: boolean
      title: InstancePut represents the modifiable fields of a LXD instance.
      type: object
    

• modify_instance_metadata

  Updates a subset of the instance image metadata.

  • name: string, required

  • project: string, optional

  • body: metadata, required

      description: ImageMetadata represents LXD image metadata (used in image tarball)
      properties:
        architecture:
          description: Architecture name
          example: x86_64
          type: string
        creation_date:
          description: Image creation data (as UNIX epoch)
          example: 1620655439
          format: int64
          type: integer
        expiry_date:
          description: Image expiry data (as UNIX epoch)
          example: 1620685757
          format: int64
          type: integer
        properties:
          additionalProperties:
            type: string
          description: Descriptive properties
          example:
            os: Ubuntu
            release: focal
            variant: cloud
          type: object
        templates:
          additionalProperties:
            $ref: '#/definitions/ImageMetadataTemplate'
          description: Template for files in the image
          type: object
      type: object
    

• modify_instance_snapshot

  Updates a subset of the snapshot config.

  • name: string, required

  • snapshot: string, required

  • project: string, optional

  • body: snapshot, optional

      properties:
        expires_at:
          description: When the snapshot expires (gets auto-deleted)
          example: 2021-03-23T17:38:37.753398689-04:00
          format: date-time
          type: string
      title: InstanceSnapshotPut represents the modifiable fields of a LXD instance snapshot.
      type: object
    

• rename_instance_backup

  Renames an instance backup.

  • backup: string, required

  • name: string, required

  • project: string, optional

  • body: backup, optional

      properties:
        name:
          description: New backup name
          example: backup1
          type: string
      title: InstanceBackupPost represents the fields available for the renaming of a instance backup.
      type: object
    

Metrics

• metrics

  Gets metrics of instances.

  • project: string, optional

Network ACLs

• create_network_acl

  Creates a new network ACL.

  • project: string, optional

  • body: acl, required

      properties:
        config:
          additionalProperties:
            type: string
          description: ACL configuration map (refer to doc/network-acls.md)
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the ACL
          example: Web servers
          type: string
        egress:
          description: List of egress rules (order independent)
          items:
            $ref: '#/definitions/NetworkACLRule'
          type: array
        ingress:
          description: List of ingress rules (order independent)
          items:
            $ref: '#/definitions/NetworkACLRule'
          type: array
        name:
          description: The new name for the ACL
          example: bar
          type: string
      title: NetworkACLsPost used for creating an ACL.
      type: object
    

• delete_network_acl

  Removes the network ACL.

  • name: string, required
  • project: string, optional

• modify_network_acl

  Updates a subset of the network ACL configuration.

  • name: string, required

  • project: string, optional

  • body: acl, required

      properties:
        config:
          additionalProperties:
            type: string
          description: ACL configuration map (refer to doc/network-acls.md)
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the ACL
          example: Web servers
          type: string
        egress:
          description: List of egress rules (order independent)
          items:
            $ref: '#/definitions/NetworkACLRule'
          type: array
        ingress:
          description: List of ingress rules (order independent)
          items:
            $ref: '#/definitions/NetworkACLRule'
          type: array
      title: NetworkACLPut used for updating an ACL.
      type: object
    

• network_acl

  Gets a specific network ACL.

  Updates the entire network ACL configuration.

  • name: string, required

  • project: string, optional

  • body: acl, required

      properties:
        config:
          additionalProperties:
            type: string
          description: ACL configuration map (refer to doc/network-acls.md)
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the ACL
          example: Web servers
          type: string
        egress:
          description: List of egress rules (order independent)
          items:
            $ref: '#/definitions/NetworkACLRule'
          type: array
        ingress:
          description: List of ingress rules (order independent)
          items:
            $ref: '#/definitions/NetworkACLRule'
          type: array
      title: NetworkACLPut used for updating an ACL.
      type: object
    

• network_acl_log

  Gets a specific network ACL log entries.

  • name: string, required
  • project: string, optional

• network_acls

  Returns a list of network ACLs (URLs).

  • project: string, optional

• network_acls_recursion1

  Returns a list of network ACLs (structs).

  • project: string, optional

• rename_network_acl

  Renames an existing network ACL.

  • name: string, required

  • project: string, optional

  • body: acl, required

      properties:
        name:
          description: The new name for the ACL
          example: bar
          type: string
      title: NetworkACLPost used for renaming an ACL.
      type: object
    

Network Forwards

• create_network_forward

  Creates a new network address forward.

  • networkName: string, required

  • project: string, optional

  • body: forward, required

      description: NetworkForwardsPost represents the fields of a new LXD network address forward
      properties:
        config:
          additionalProperties:
            type: string
          description: Forward configuration map (refer to doc/network-forwards.md)
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the forward listen IP
          example: My public IP forward
          type: string
        listen_address:
          description: The listen address of the forward
          example: 192.0.2.1
          type: string
        ports:
          description: Port forwards (optional)
          items:
            $ref: '#/definitions/NetworkForwardPort'
          type: array
      type: object
    

• delete_network_forward

  Removes the network address forward.

  • listenAddress: string, required
  • networkName: string, required
  • project: string, optional

• modify_network_forward

  Updates a subset of the network address forward configuration.

  • listenAddress: string, required

  • networkName: string, required

  • project: string, optional

  • body: forward, required

      description: NetworkForwardPut represents the modifiable fields of a LXD network address forward
      properties:
        config:
          additionalProperties:
            type: string
          description: Forward configuration map (refer to doc/network-forwards.md)
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the forward listen IP
          example: My public IP forward
          type: string
        ports:
          description: Port forwards (optional)
          items:
            $ref: '#/definitions/NetworkForwardPort'
          type: array
      type: object
    

• network_forward

  Gets a specific network address forward.

  Updates the entire network address forward configuration.

  • listenAddress: string, required

  • networkName: string, required

  • project: string, optional

  • body: forward, required

      description: NetworkForwardPut represents the modifiable fields of a LXD network address forward
      properties:
        config:
          additionalProperties:
            type: string
          description: Forward configuration map (refer to doc/network-forwards.md)
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the forward listen IP
          example: My public IP forward
          type: string
        ports:
          description: Port forwards (optional)
          items:
            $ref: '#/definitions/NetworkForwardPort'
          type: array
      type: object
    

• network_forward_recursion1

  Returns a list of network address forwards (structs).

  • networkName: string, required
  • project: string, optional

• network_forwards

  Returns a list of network address forwards (URLs).

  • networkName: string, required
  • project: string, optional

Network Peers

• create_network_peer

  Initiates/creates a new network peering.

  • networkName: string, required

  • project: string, optional

  • body: peer, required

      description: NetworkPeersPost represents the fields of a new LXD network peering
      properties:
        config:
          additionalProperties:
            type: string
          description: Peer configuration map (refer to doc/network-peers.md)
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the peer
          example: Peering with network1 in project1
          type: string
        name:
          description: Name of the peer
          example: project1-network1
          type: string
        target_network:
          description: Name of the target network
          example: network1
          type: string
        target_project:
          description: Name of the target project
          example: project1
          type: string
      type: object
    

• delete_network_peer

  Removes the network peering.

  • networkName: string, required
  • peerName: string, required
  • project: string, optional

• modify_network_peer

  Updates a subset of the network peering configuration.

  • networkName: string, required

  • peerName: string, required

  • project: string, optional

  • body: Peer, required

      description: NetworkPeerPut represents the modifiable fields of a LXD network peering
      properties:
        config:
          additionalProperties:
            type: string
          description: Peer configuration map (refer to doc/network-peers.md)
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the peer
          example: Peering with network1 in project1
          type: string
      type: object
    

• network_peer

  Gets a specific network peering.

  Updates the entire network peering configuration.

  • networkName: string, required

  • peerName: string, required

  • project: string, optional

  • body: peer, required

      description: NetworkPeerPut represents the modifiable fields of a LXD network peering
      properties:
        config:
          additionalProperties:
            type: string
          description: Peer configuration map (refer to doc/network-peers.md)
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the peer
          example: Peering with network1 in project1
          type: string
      type: object
    

• network_peer_recursion1

  Returns a list of network peers (structs).

  • networkName: string, required
  • project: string, optional

• network_peers

  Returns a list of network peers (URLs).

  • networkName: string, required
  • project: string, optional

Network Zones

• create_network_zone

  Creates a new network zone.

  • project: string, optional

  • body: zone, required

      description: NetworkZonesPost represents the fields of a new LXD network zone
      properties:
        config:
          additionalProperties:
            type: string
          description: Zone configuration map (refer to doc/network-zones.md)
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the network zone
          example: Internal domain
          type: string
        name:
          description: The name of the zone (DNS domain name)
          example: example.net
          type: string
      type: object
    

• create_network_zone_record

  Creates a new network zone record.

  • zone: string, required

  • project: string, optional

  • body: zone, required

      description: NetworkZoneRecordsPost represents the fields of a new LXD network zone record
      properties:
        config:
          additionalProperties:
            type: string
          description: Advanced configuration for the record
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the record
          example: SPF record
          type: string
        entries:
          description: Entries in the record
          items:
            $ref: '#/definitions/NetworkZoneRecordEntry'
          type: array
        name:
          description: The record name in the zone
          example: '@'
          type: string
      type: object
    

• delete_network_zone

  Removes the network zone.

  • name: string, required
  • project: string, optional

• delete_network_zone_record

  Removes the network zone record.

  • name: string, required
  • zone: string, required
  • project: string, optional

• modify_network_zone

  Updates a subset of the network zone configuration.

  • name: string, required

  • project: string, optional

  • body: zone, required

      description: NetworkZonePut represents the modifiable fields of a LXD network zone
      properties:
        config:
          additionalProperties:
            type: string
          description: Zone configuration map (refer to doc/network-zones.md)
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the network zone
          example: Internal domain
          type: string
      type: object
    

• modify_network_zone_record

  Updates a subset of the network zone record configuration.

  • name: string, required

  • zone: string, required

  • project: string, optional

  • body: zone, required

      description: NetworkZoneRecordPut represents the modifiable fields of a LXD network zone record
      properties:
        config:
          additionalProperties:
            type: string
          description: Advanced configuration for the record
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the record
          example: SPF record
          type: string
        entries:
          description: Entries in the record
          items:
            $ref: '#/definitions/NetworkZoneRecordEntry'
          type: array
      type: object
    

• network_zone

  Gets a specific network zone.

  Updates the entire network zone configuration.

  • name: string, required

  • project: string, optional

  • body: zone, required

      description: NetworkZonePut represents the modifiable fields of a LXD network zone
      properties:
        config:
          additionalProperties:
            type: string
          description: Zone configuration map (refer to doc/network-zones.md)
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the network zone
          example: Internal domain
          type: string
      type: object
    

• network_zone_record

  Gets a specific network zone record.

  Updates the entire network zone record configuration.

  • name: string, required

  • zone: string, required

  • project: string, optional

  • body: zone, required

      description: NetworkZoneRecordPut represents the modifiable fields of a LXD network zone record
      properties:
        config:
          additionalProperties:
            type: string
          description: Advanced configuration for the record
          example:
            user.mykey: foo
          type: object
        description:
          description: Description of the record
          example: SPF record
          type: string
        entries:
          description: Entries in the record
          items:
            $ref: '#/definitions/NetworkZoneRecordEntry'
          type: array
      type: object
    

• network_zone_records

  Returns a list of network zone records (URLs).

  • zone: string, required
  • project: string, optional

• network_zone_records_recursion1

  Returns a list of network zone records (structs).

  • zone: string, required
  • project: string, optional

• network_zones

  Returns a list of network zones (URLs).

  • project: string, optional

• network_zones_recursion1

  Returns a list of network zones (structs).

  • project: string, optional

Networks

• create_network

  Creates a new network. When clustered, most network types require individual POST for each cluster member prior to a global POST.

  • project: string, optional

  • target: string, optional

  • body: network, required

      description: NetworksPost represents the fields of a new LXD network
      properties:
        config:
          additionalProperties:
            type: string
          description: Network configuration map (refer to doc/networks.md)
          example:
            ipv4.address: 10.0.0.1/24
            ipv4.nat: true
            ipv6.address: none
          type: object
        description:
          description: Description of the profile
          example: My new LXD bridge
          type: string
        name:
          description: The name of the new network
          example: lxdbr1
          type: string
        type:
          description: The network type (refer to doc/networks.md)
          example: bridge
          type: string
      type: object
    

• delete_network

  Removes the network.

  • name: string, required
  • project: string, optional

• modify_network

  Updates a subset of the network configuration.

  • name: string, required

  • project: string, optional

  • target: string, optional

  • body: network, required

      description: NetworkPut represents the modifiable fields of a LXD network
      properties:
        config:
          additionalProperties:
            type: string
          description: Network configuration map (refer to doc/networks.md)
          example:
            ipv4.address: 10.0.0.1/24
            ipv4.nat: true
            ipv6.address: none
          type: object
        description:
          description: Description of the profile
          example: My new LXD bridge
          type: string
      type: object
    

• network

  Gets a specific network.

  Updates the entire network configuration.

  • name: string, required

  • project: string, optional

  • target: string, optional

  • body: network, required

      description: NetworkPut represents the modifiable fields of a LXD network
      properties:
        config:
          additionalProperties:
            type: string
          description: Network configuration map (refer to doc/networks.md)
          example:
            ipv4.address: 10.0.0.1/24
            ipv4.nat: true
            ipv6.address: none
          type: object
        description:
          description: Description of the profile
          example: My new LXD bridge
          type: string
      type: object
    

• networks

  Returns a list of networks (URLs).

  • project: string, optional

• networks_leases

  Returns a list of DHCP leases for the network.

  • name: string, required
  • project: string, optional
  • target: string, optional

• networks_recursion1

  Returns a list of networks (structs).

  • project: string, optional

• networks_state

  Returns the current network state information.

  • name: string, required
  • project: string, optional
  • target: string, optional

• rename_network

  Renames an existing network.

  • name: string, required

  • project: string, optional

  • body: network, required

      description: NetworkPost represents the fields required to rename a LXD network
      properties:
        name:
          description: The new name for the network
          example: lxdbr1
          type: string
      type: object
    

Operations

• delete_operation

  Cancels the operation if supported.

  • id: string, required

• operation

  Gets the operation state.

  • id: string, required

• operation_wait

  Waits for the operation to reach a final state (or timeout) and retrieve its final state.

  • id: string, required
  • timeout: integer, optional

• operation_wait_untrusted

  Waits for the operation to reach a final state (or timeout) and retrieve its final state.

  When accessed by an untrusted user, the secret token must be provided.

  • id: string, required
  • secret: string, optional
  • timeout: integer, optional

• operation_websocket

  Connects to an associated websocket stream for the operation. This should almost never be done directly by a client, instead it's meant for LXD to LXD communication with the client only relaying the connection information to the servers.

  • id: string, required
  • secret: string, optional

• operation_websocket_untrusted

  Connects to an associated websocket stream for the operation. This should almost never be done directly by a client, instead it's meant for LXD to LXD communication with the client only relaying the connection information to the servers.

  The untrusted endpoint is used by the target server to connect to the source server. Authentication is performed through the secret token.

  • id: string, required
  • secret: string, optional

• operations

  Returns a dict of operation type to operation list (URLs).

• operations_recursion1

  Returns a list of operations (structs).

  • project: string, optional

Profiles

• create_profile

  Creates a new profile.

  • project: string, optional

  • body: profile, required

      description: ProfilesPost represents the fields of a new LXD profile
      properties:
        config:
          additionalProperties:
            type: string
          description: Instance configuration map (refer to doc/instances.md)
          example:
            limits.cpu: 4
            limits.memory: 4GiB
          type: object
        description:
          description: Description of the profile
          example: Medium size instances
          type: string
        devices:
          additionalProperties:
            additionalProperties:
              type: string
            type: object
          description: List of devices
          example:
            eth0:
              name: eth0
              network: lxdbr0
              type: nic
            root:
              path: /
              pool: default
              type: disk
          type: object
        name:
          description: The name of the new profile
          example: foo
          type: string
      type: object
    

• delete_profile

  Removes the profile.

  • name: string, required
  • project: string, optional

• modify_profile

  Updates a subset of the profile configuration.

  • name: string, required

  • project: string, optional

  • body: profile, required

      description: ProfilePut represents the modifiable fields of a LXD profile
      properties:
        config:
          additionalProperties:
            type: string
          description: Instance configuration map (refer to doc/instances.md)
          example:
            limits.cpu: 4
            limits.memory: 4GiB
          type: object
        description:
          description: Description of the profile
          example: Medium size instances
          type: string
        devices:
          additionalProperties:
            additionalProperties:
              type: string
            type: object
          description: List of devices
          example:
            eth0:
              name: eth0
              network: lxdbr0
              type: nic
            root:
              path: /
              pool: default
              type: disk
          type: object
      type: object
    

• profile

  Gets a specific profile.

  Updates the entire profile configuration.

  • name: string, required

  • project: string, optional

  • body: profile, required

      description: ProfilePut represents the modifiable fields of a LXD profile
      properties:
        config:
          additionalProperties:
            type: string
          description: Instance configuration map (refer to doc/instances.md)
          example:
            limits.cpu: 4
            limits.memory: 4GiB
          type: object
        description:
          description: Description of the profile
          example: Medium size instances
          type: string
        devices:
          additionalProperties:
            additionalProperties:
              type: string
            type: object
          description: List of devices
          example:
            eth0:
              name: eth0
              network: lxdbr0
              type: nic
            root:
              path: /
              pool: default
              type: disk
          type: object
      type: object
    

• profiles

  Returns a list of profiles (URLs).

  • project: string, optional

• profiles_recursion1

  Returns a list of profiles (structs).

  • project: string, optional

• rename_profile

  Renames an existing profile.

  • name: string, required

  • project: string, optional

  • body: profile, required

      description: ProfilePost represents the fields required to rename a LXD profile
      properties:
        name:
          description: The new name for the profile
          example: bar
          type: string
      type: object
    

Projects

• create_project

  Creates a new project.

  • body: project, required

      description: ProjectsPost represents the fields of a new LXD project
      properties:
        config:
          additionalProperties:
            type: string
          description: Project configuration map (refer to doc/projects.md)
          example:
            features.networks: false
            features.profiles: true
          type: object
        description:
          description: Description of the project
          example: My new project
          type: string
        name:
          description: The name of the new project
          example: foo
          type: string
      type: object
    

• delete_project

  Removes the project.

  • name: string, required

• modify_project

  Updates a subset of the project configuration.

  • name: string, required

  • body: project, required

      description: ProjectPut represents the modifiable fields of a LXD project
      properties:
        config:
          additionalProperties:
            type: string
          description: Project configuration map (refer to doc/projects.md)
          example:
            features.networks: false
            features.profiles: true
          type: object
        description:
          description: Description of the project
          example: My new project
          type: string
      type: object
    

• project

  Gets a specific project.

  Updates the entire project configuration.

  • name: string, required

  • body: project, required

      description: ProjectPut represents the modifiable fields of a LXD project
      properties:
        config:
          additionalProperties:
            type: string
          description: Project configuration map (refer to doc/projects.md)
          example:
            features.networks: false
            features.profiles: true
          type: object
        description:
          description: Description of the project
          example: My new project
          type: string
      type: object
    

• project_state

  Gets a specific project resource consumption information.

  • name: string, required

• projects

  Returns a list of projects (URLs).

• projects_recursion1

  Returns a list of projects (structs).

• rename_project

  Renames an existing project.

  • name: string, required

  • body: project, required

      description: ProjectPost represents the fields required to rename a LXD project
      properties:
        name:
          description: The new name for the project
          example: bar
          type: string
      type: object
    

Server

• api

  Returns a list of supported API versions (URLs).

  Internal API endpoints are not reported as those aren't versioned and should only be used by LXD itself.

• events

  Connects to the event API using websocket.

  • project: string, optional
  • type: string, optional

• modify_server

  Updates a subset of the server configuration.

  • target: string, optional

  • body: server, required

      description: ServerPut represents the modifiable fields of a LXD server configuration
      properties:
        config:
          additionalProperties:
            type: object
          description: Server configuration map (refer to doc/server.md)
          example:
            core.https_address: :8443
            core.trust_password: true
          type: object
      type: object
    

• resources

  Gets the hardware information profile of the LXD server.

  • target: string, optional

• server

  Shows the full server environment and configuration.

  Updates the entire server configuration.

  • project: string, optional

  • target: string, optional

  • body: server, required

      description: ServerPut represents the modifiable fields of a LXD server configuration
      properties:
        config:
          additionalProperties:
            type: object
          description: Server configuration map (refer to doc/server.md)
          example:
            core.https_address: :8443
            core.trust_password: true
          type: object
      type: object
    

• server_untrusted

  Shows a small subset of the server environment and configuration which is required by untrusted clients to reach a server.

  The `?public` part of the URL isn't required, it's simply used to separate the two behaviors of this endpoint.

Storage

• create_storage_pool

  Creates a new storage pool. When clustered, storage pools require individual POST for each cluster member prior to a global POST.

  • project: string, optional

  • target: string, optional

  • body: storage, required

      description: StoragePoolsPost represents the fields of a new LXD storage pool
      properties:
        config:
          additionalProperties:
            type: string
          description: Storage pool configuration map (refer to doc/storage.md)
          example:
            volume.block.filesystem: ext4
            volume.size: 50GiB
          type: object
        description:
          description: Description of the storage pool
          example: Local SSD pool
          type: string
        driver:
          description: 'Storage pool driver (btrfs, ceph, cephfs, dir, lvm or zfs)'
          example: zfs
          type: string
        name:
          description: Storage pool name
          example: local
          type: string
      type: object
    

• create_storage_pool_volume

  Creates a new storage volume.

  • name: string, required

  • project: string, optional

  • target: string, optional

  • body: volume, required

      description: StorageVolumesPost represents the fields of a new LXD storage pool volume
      properties:
        config:
          additionalProperties:
            type: string
          description: Storage volume configuration map (refer to doc/storage.md)
          example:
            size: 50GiB
            zfs.remove_snapshots: true
          type: object
        content_type:
          description: Volume content type (filesystem or block)
          example: filesystem
          type: string
        description:
          description: Description of the storage volume
          example: My custom volume
          type: string
        name:
          description: Volume name
          example: foo
          type: string
        restore:
          description: Name of a snapshot to restore
          example: snap0
          type: string
        source:
          $ref: '#/definitions/StorageVolumeSource'
        type:
          description: 'Volume type (container, custom, image or virtual-machine)'
          example: custom
          type: string
      type: object
    

• create_storage_pool_volumes_backup

  Creates a new storage volume backup.

  • name: string, required

  • type: string, required

  • volume: string, required

  • project: string, optional

  • target: string, optional

  • body: volume, required

      description: StoragePoolVolumeBackupsPost represents the fields available for a new LXD volume backup
      properties:
        compression_algorithm:
          description: What compression algorithm to use
          example: gzip
          type: string
        expires_at:
          description: When the backup expires (gets auto-deleted)
          example: 2021-03-23T17:38:37.753398689-04:00
          format: date-time
          type: string
        name:
          description: Backup name
          example: backup0
          type: string
        optimized_storage:
          description: Whether to use a pool-optimized binary format (instead of plain tarball)
          example: true
          type: boolean
        volume_only:
          description: Whether to ignore snapshots
          example: false
          type: boolean
      type: object
    

• create_storage_pool_volumes_snapshot

  Creates a new storage volume snapshot.

  • name: string, required

  • type: string, required

  • volume: string, required

  • project: string, optional

  • target: string, optional

  • body: volume, required

      description: StorageVolumeSnapshotsPost represents the fields available for a new LXD storage volume snapshot
      properties:
        expires_at:
          description: When the snapshot expires (gets auto-deleted)
          example: 2021-03-23T17:38:37.753398689-04:00
          format: date-time
          type: string
        name:
          description: Snapshot name
          example: snap0
          type: string
      type: object
    

• create_storage_pool_volumes_type

  Creates a new storage volume (type specific endpoint).

  • name: string, required

  • type: string, required

  • project: string, optional

  • target: string, optional

  • body: volume, required

      description: StorageVolumesPost represents the fields of a new LXD storage pool volume
      properties:
        config:
          additionalProperties:
            type: string
          description: Storage volume configuration map (refer to doc/storage.md)
          example:
            size: 50GiB
            zfs.remove_snapshots: true
          type: object
        content_type:
          description: Volume content type (filesystem or block)
          example: filesystem
          type: string
        description:
          description: Description of the storage volume
          example: My custom volume
          type: string
        name:
          description: Volume name
          example: foo
          type: string
        restore:
          description: Name of a snapshot to restore
          example: snap0
          type: string
        source:
          $ref: '#/definitions/StorageVolumeSource'
        type:
          description: 'Volume type (container, custom, image or virtual-machine)'
          example: custom
          type: string
      type: object
    

• delete_storage_pool_volume_type

  Removes the storage volume.

  • name: string, required
  • type: string, required
  • volume: string, required
  • project: string, optional
  • target: string, optional

• delete_storage_pool_volumes_type_backup

  Deletes a new storage volume backup.

  • backup: string, required
  • name: string, required
  • type: string, required
  • volume: string, required
  • project: string, optional
  • target: string, optional

• delete_storage_pool_volumes_type_snapshot

  Deletes a new storage volume snapshot.

  • name: string, required
  • snapshot: string, required
  • type: string, required
  • volume: string, required
  • project: string, optional
  • target: string, optional

• delete_storage_pools

  Removes the storage pool.

  • name: string, required
  • project: string, optional

• migrate_storage_pool_volume_type

  Renames, moves a storage volume between pools or migrates an instance to another server.

  The returned operation metadata will vary based on what's requested. For rename or move within the same server, this is a simple background operation with progress data. For migration, in the push case, this will similarly be a background operation with progress data, for the pull case, it will be a websocket operation with a number of secrets to be passed to the target server.

  • name: string, required

  • type: string, required

  • volume: string, required

  • project: string, optional

  • target: string, optional

  • body: migration, optional

      description: StorageVolumePost represents the fields required to rename a LXD storage pool volume
      properties:
        migration:
          description: Initiate volume migration
          example: false
          type: boolean
        name:
          description: New volume name
          example: foo
          type: string
        pool:
          description: New storage pool
          example: remote
          type: string
        project:
          description: New project name
          example: foo
          type: string
        target:
          $ref: '#/definitions/StorageVolumePostTarget'
        volume_only:
          description: Whether snapshots should be discarded (migration only)
          example: false
          type: boolean
      type: object
    

• modify_storage_pool

  Updates a subset of the storage pool configuration.

  • name: string, required

  • project: string, optional

  • target: string, optional

  • body: storage pool, required

      properties:
        config:
          additionalProperties:
            type: string
          description: Storage pool configuration map (refer to doc/storage.md)
          example:
            volume.block.filesystem: ext4
            volume.size: 50GiB
          type: object
        description:
          description: Description of the storage pool
          example: Local SSD pool
          type: string
      title: StoragePoolPut represents the modifiable fields of a LXD storage pool.
      type: object
    

• modify_storage_pool_volume_type

  Updates a subset of the storage volume configuration.

  • name: string, required

  • type: string, required

  • volume: string, required

  • project: string, optional

  • target: string, optional

  • body: storage volume, required

      description: StorageVolumePut represents the modifiable fields of a LXD storage volume
      properties:
        config:
          additionalProperties:
            type: string
          description: Storage volume configuration map (refer to doc/storage.md)
          example:
            size: 50GiB
            zfs.remove_snapshots: true
          type: object
        description:
          description: Description of the storage volume
          example: My custom volume
          type: string
        restore:
          description: Name of a snapshot to restore
          example: snap0
          type: string
      type: object
    

• modify_storage_pool_volumes_type_snapshot

  Updates a subset of the storage volume snapshot configuration.

  • name: string, required

  • snapshot: string, required

  • type: string, required

  • volume: string, required

  • project: string, optional

  • target: string, optional

  • body: storage volume snapshot, required

      description: StorageVolumeSnapshotPut represents the modifiable fields of a LXD storage volume
      properties:
        description:
          description: Description of the storage volume
          example: My custom volume
          type: string
        expires_at:
          description: When the snapshot expires (gets auto-deleted)
          example: 2021-03-23T17:38:37.753398689-04:00
          format: date-time
          type: string
      type: object
    

• rename_storage_pool_volumes_type_backup

  Renames a storage volume backup.

  • backup: string, required

  • name: string, required

  • type: string, required

  • volume: string, required

  • project: string, optional

  • target: string, optional

  • body: volume rename, required

      description: StorageVolumeSnapshotPost represents the fields required to rename/move a LXD storage volume snapshot
      properties:
        name:
          description: New snapshot name
          example: snap1
          type: string
      type: object
    

• rename_storage_pool_volumes_type_snapshot

  Renames a storage volume snapshot.

  • name: string, required

  • snapshot: string, required

  • type: string, required

  • volume: string, required

  • project: string, optional

  • target: string, optional

  • body: volume rename, required

      description: StorageVolumeSnapshotPost represents the fields required to rename/move a LXD storage volume snapshot
      properties:
        name:
          description: New snapshot name
          example: snap1
          type: string
      type: object
    

• storage_pool

  Gets a specific storage pool.

  Updates the entire storage pool configuration.

  • name: string, required

  • project: string, optional

  • target: string, optional

  • body: storage pool, required

      properties:
        config:
          additionalProperties:
            type: string
          description: Storage pool configuration map (refer to doc/storage.md)
          example:
            volume.block.filesystem: ext4
            volume.size: 50GiB
          type: object
        description:
          description: Description of the storage pool
          example: Local SSD pool
          type: string
      title: StoragePoolPut represents the modifiable fields of a LXD storage pool.
      type: object
    

• storage_pool_resources

  Gets the usage information for the storage pool.

  • name: string, required
  • target: string, optional

• storage_pool_volume_type

  Gets a specific storage volume.

  Updates the entire storage volume configuration.

  • name: string, required

  • type: string, required

  • volume: string, required

  • project: string, optional

  • target: string, optional

  • body: storage volume, required

      description: StorageVolumePut represents the modifiable fields of a LXD storage volume
      properties:
        config:
          additionalProperties:
            type: string
          description: Storage volume configuration map (refer to doc/storage.md)
          example:
            size: 50GiB
            zfs.remove_snapshots: true
          type: object
        description:
          description: Description of the storage volume
          example: My custom volume
          type: string
        restore:
          description: Name of a snapshot to restore
          example: snap0
          type: string
      type: object
    

• storage_pool_volume_type_state

  Gets a specific storage volume state (usage data).

  • name: string, required
  • type: string, required
  • volume: string, required
  • project: string, optional
  • target: string, optional

• storage_pool_volumes

  Returns a list of storage volumes (URLs).

  • name: string, required
  • filter: string, optional
  • project: string, optional
  • target: string, optional

• storage_pool_volumes_recursion1

  Returns a list of storage volumes (structs).

  • name: string, required
  • filter: string, optional
  • project: string, optional
  • target: string, optional

• storage_pool_volumes_type

  Returns a list of storage volumes (URLs) (type specific endpoint).

  • name: string, required
  • type: string, required
  • project: string, optional
  • target: string, optional

• storage_pool_volumes_type_backup

  Gets a specific storage volume backup.

  • backup: string, required
  • name: string, required
  • type: string, required
  • volume: string, required
  • project: string, optional
  • target: string, optional

• storage_pool_volumes_type_backup_export

  Download the raw backup file from the server.

  • backup: string, required
  • name: string, required
  • type: string, required
  • volume: string, required
  • project: string, optional
  • target: string, optional

• storage_pool_volumes_type_backups

  Returns a list of storage volume backups (URLs).

  • name: string, required
  • type: string, required
  • volume: string, required
  • project: string, optional
  • target: string, optional

• storage_pool_volumes_type_backups_recursion1

  Returns a list of storage volume backups (structs).

  • name: string, required
  • type: string, required
  • volume: string, required
  • project: string, optional
  • target: string, optional

• storage_pool_volumes_type_recursion1

  Returns a list of storage volumes (structs) (type specific endpoint).

  • name: string, required
  • type: string, required
  • project: string, optional
  • target: string, optional

• storage_pool_volumes_type_snapshot

  Gets a specific storage volume snapshot.

  Updates the entire storage volume snapshot configuration.

  • name: string, required

  • snapshot: string, required

  • type: string, required

  • volume: string, required

  • project: string, optional

  • target: string, optional

  • body: storage volume snapshot, required

      description: StorageVolumeSnapshotPut represents the modifiable fields of a LXD storage volume
      properties:
        description:
          description: Description of the storage volume
          example: My custom volume
          type: string
        expires_at:
          description: When the snapshot expires (gets auto-deleted)
          example: 2021-03-23T17:38:37.753398689-04:00
          format: date-time
          type: string
      type: object
    

• storage_pool_volumes_type_snapshots

  Returns a list of storage volume snapshots (URLs).

  • name: string, required
  • type: string, required
  • volume: string, required
  • project: string, optional
  • target: string, optional

• storage_pool_volumes_type_snapshots_recursion1

  Returns a list of storage volume snapshots (structs).

  • name: string, required
  • type: string, required
  • volume: string, required
  • project: string, optional
  • target: string, optional

• storage_pools

  Returns a list of storage pools (URLs).

  • project: string, optional

• storage_pools_recursion1

  Returns a list of storage pools (structs).

  • project: string, optional

Warnings

• delete_warning

  Removes the warning.

  • uuid: string, required

• modify_warning

  Updates a subset of the warning status.

  • uuid: string, required

  • body: warning, required

      properties:
        status:
          description: 'Status of the warning (new, acknowledged, or resolved)'
          example: new
          type: string
      title: WarningPut represents the modifiable fields of a warning.
      type: object
    

• warning

  Gets a specific warning.

  Updates the warning status.

  • uuid: string, required

  • body: warning, required

      properties:
        status:
          description: 'Status of the warning (new, acknowledged, or resolved)'
          example: new
          type: string
      title: WarningPut represents the modifiable fields of a warning.
      type: object
    

• warnings

  Returns a list of warnings.

  • project: string, optional

• warnings_recursion1

  Returns a list of warnings (structs).

  • project: string, optional

PSEUDO OBJECT ORIENTATION

Just for the sake of experimentation, I added a sub-package lxd::instance. To add OO-flavour, you simply bless the instance HASH with it:

my $r = $lxd->instance( name => "my-container" )->get;
my $i = bless $r, 'lxd::instance';

From then on, the following methods can operate on it:

• restart
• start
• freeze
• unfreeze
• stop
• state

Well, I'm not a big fan of objects.

EXAMPLES

I encourage you to look at the 02_instances.t test suite. It will show a complete life cycle for containers.

SEE ALSO

• Linux::LXC

  uses actually the existing lxc client to get the information

• https://github.com/jipipayo/Linux-REST-LXD

  pretty old, never persued

HINTS

• How to generate an SSL client certificate for LXD

  First, I found one client certificate (plus the key) in my installation at:

    /root/snap/lxd/common/config/
  

  Alternatively, you can run your own small CA, generate a .crt and .key for a client, and then add it to lxd to trust it.

  More on this topic is here

• How to find the SSL fingerprint for an LXD server

  With recent versions of LXD this is fairly easy:

    $ lxc info|grep fingerprint
  

  It is a SHA256 hash, so you will have to prefix it with sha256$ (no blanks) when you pass it to SSL_fingerprint.

  Alternatively, you can try to find the server certificate and use openssl to derive a fingerprint of your choice.

• How to add/modify specific HTTP modalities (proxy, connection pooling, ...)

  The property _http holds the async HTTP client of class Net::Async::HTTP. That way you can reconfigure it via

    $lxd->_http->configure(user_agent => "My Client");
    $lxd->_http->configure( +headers => { One_More => "Key" } );
  

ISSUES

Open issues are probably best put onto Github

AUTHOR

Robert Barta, <rho at devc.at>

CREDITS

IO::Async, Net::Async::HTTP, IO::Socket::SSL and friends are amazing.

LICENSE AND COPYRIGHT

Copyright 2022 Robert Barta.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.