The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
Net-Async-WebService-lxd-0.03
River stage zero No dependents
/ Net::Async::WebService::lxd

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

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.

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.