
=head1 NAME

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

=head1 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


=head1 INTERFACE

=head2 Constructor

The constructor returns a handle to one LXD server. It's address is specified via an B<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 B<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 C<default> one, of course.

As we are operating under an L<IO::Async> regime here, the handle also needs a B<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 B<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
L<IO::Socket::SSL|https://metacpan.org/pod/IO::Socket::SSL#Description-Of-Methods>. But, specifically,
one should consider to provide:

=over

=item * B<client certificate>, via a proper subset of C<SSL_cert_file>, C<SSL_key_file>, C<SSL_cert> and C<SSL_key>.
(Look at the L</HINTS> section to generate such a certificate for LXD.)

=item * B<server fingerprint>, via C<SSL_fingerprint>
(Look at the L</HINTS> section how to figure this out.)

=back

=head2 Methods

All methods below are automatically generated from the L<LXD REST API Spec|https://raw.githubusercontent.com/lxc/lxd/master/doc/rest-api.yaml>.
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;

=over

=item *

All invocations return a L<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 C<-E<gt>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 C<done> or C<failed>. Normally, you will never need
to use the methods for 'Operations' yourself; they are still offered as fallback.

=item *

The result of each fully completed invocation is either

=over

=item *

the string C<success>, or

=item *

a Perl HASH ref which reflects the JSON data sent from the LXD server. Note, that Booleans have to
be treated special, by using C<JSON::false> and C<JSON::true>. Otherwise, they follow B<exactly> the
structure in the specification.

=item *

or a HASH ref with keys C<stdin> and C<stdout> if this is a result of the C<execute_in_instance>
method.

=back

=item *

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 C<IO::Async> -
raise an exception, with the failure as string.

=item *

Methods named like the type of server object (e.g. C<cluster>, C<certificate>, C<image>) are
normally "getter/setter" methods. The getter obviously returns the state of the object. The method
becomes a setter, if the additional C<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 C<name>,
C<id>, C<fingerprint>, or similar. You may also have to provide a C<project>, if not being the
I<default project>.

=item *

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

=item *

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

=over

=item *

Methods which change the state of the remote object usually are called C<modify>_I<something>.

=item *

Methods which add a new object to a collection are usually called C<add>_I<something>, or
C<create>_I<something>, depending on how it sounds better.

=item *

Methods which remove an object from a collection are usually called C<delete>_I<something>.

=back

=back

=head2 Certificates

=over

=item * B<add_certificate>

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

=over

=item C<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



=back

=item * B<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.

=over

=item C<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



=back

=item * B<certificate>

Gets a specific certificate entry from the trust store.

Updates the entire certificate configuration.

=over

=item C<fingerprint>: string, required

=item C<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



=back

=item * B<certificates>

Returns a list of trusted certificates (URLs).

=over



=back

=item * B<certificates_recursion1>

Returns a list of trusted certificates (structs).

=over



=back

=item * B<delete_certificate>

Removes the certificate from the trust store.

=over

=item C<fingerprint>: string, required



=back

=item * B<modify_certificate>

Updates a subset of the certificate configuration.

=over

=item C<fingerprint>: string, required

=item C<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



=back



=back

=head2 Cluster

=over

=item * B<add_cluster_member>

Requests a join token to add a cluster member.

=over

=item C<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



=back

=item * B<cluster>

Gets the current cluster configuration.

Updates the entire cluster configuration.

=over

=item C<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



=back

=item * B<cluster_member>

Gets a specific cluster member.

Updates the entire cluster member configuration.

=over

=item C<name>: string, required

=item C<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



=back

=item * B<cluster_members>

Returns a list of cluster members (URLs).

=over



=back

=item * B<cluster_members_recursion1>

Returns a list of cluster members (structs).

=over



=back

=item * B<clustering_update_cert>

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

=over

=item C<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



=back

=item * B<create_cluster_group>

Creates a new cluster group.

=over

=item C<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



=back

=item * B<delete_cluster_member>

Removes the member from the cluster.

=over

=item C<name>: string, required



=back

=item * B<modify_cluster_member>

Updates a subset of the cluster member configuration.

=over

=item C<name>: string, required

=item C<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



=back

=item * B<rename_cluster_member>

Renames an existing cluster member.

=over

=item C<name>: string, required

=item C<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



=back

=item * B<restore_cluster_member_state>

Evacuates or restores a cluster member.

=over

=item C<name>: string, required

=item C<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



=back



=back

=head2 Cluster Groups

=over

=item * B<cluster_group>

Gets a specific cluster group.

Updates the entire cluster group configuration.

=over

=item C<name>: string, required

=item C<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



=back

=item * B<cluster_groups>

Returns a list of cluster groups (URLs).

=over



=back

=item * B<cluster_groups_recursion1>

Returns a list of cluster groups (structs).

=over



=back

=item * B<delete_cluster_group>

Removes the cluster group.

=over

=item C<name>: string, required



=back

=item * B<modify_cluster_group>

Updates the cluster group configuration.

=over

=item C<name>: string, required

=item C<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



=back

=item * B<rename_cluster_group>

Renames an existing cluster group.

=over

=item C<name>: string, required

=item C<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



=back



=back

=head2 Images

=over

=item * B<add_images_alias>

Creates a new image alias.

=over

=item C<project>: string, optional

=item C<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



=back

=item * B<create_image>

Adds a new image to the image store.

=over

=item C<project>: string, optional

=item C<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

=item C<body>: raw_image, optionalsee Spec



=back

=item * B<delete_image>

Removes the image from the image store.

=over

=item C<fingerprint>: string, required

=item C<project>: string, optional



=back

=item * B<delete_image_alias>

Deletes a specific image alias.

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<image>

Gets a specific image.

Updates the entire image definition.

=over

=item C<fingerprint>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<image_alias>

Gets a specific image alias.

Updates the entire image alias configuration.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<image_alias_untrusted>

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

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<image_export>

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

=over

=item C<fingerprint>: string, required

=item C<project>: string, optional



=back

=item * B<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.

=over

=item C<fingerprint>: string, required

=item C<project>: string, optional

=item C<secret>: string, optional



=back

=item * B<image_untrusted>

Gets a specific public image.

=over

=item C<fingerprint>: string, required

=item C<project>: string, optional

=item C<secret>: string, optional



=back

=item * B<images>

Returns a list of images (URLs).

=over

=item C<filter>: string, optional

=item C<project>: string, optional



=back

=item * B<images_aliases>

Returns a list of image aliases (URLs).

=over

=item C<project>: string, optional



=back

=item * B<images_aliases_recursion1>

Returns a list of image aliases (structs).

=over

=item C<project>: string, optional



=back

=item * B<images_recursion1>

Returns a list of images (structs).

=over

=item C<filter>: string, optional

=item C<project>: string, optional



=back

=item * B<images_recursion1_untrusted>

Returns a list of publicly available images (structs).

=over

=item C<filter>: string, optional

=item C<project>: string, optional



=back

=item * B<images_untrusted>

Returns a list of publicly available images (URLs).

=over

=item C<filter>: string, optional

=item C<project>: string, optional



=back

=item * B<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.

=over

=item C<fingerprint>: string, required

=item C<project>: string, optional



=back

=item * B<modify_image>

Updates a subset of the image definition.

=over

=item C<fingerprint>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<modify_images_alias>

Updates a subset of the image alias configuration.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<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.

=over

=item C<project>: string, optional

=item C<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



=back

=item * B<push_images_export>

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

=over

=item C<fingerprint>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<rename_images_alias>

Renames an existing image alias.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<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.

=over

=item C<fingerprint>: string, required

=item C<project>: string, optional



=back



=back

=head2 Instances

=over

=item * B<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.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<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.

=over

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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

=item C<body>: raw_backup, optionalsee Spec



=back

=item * B<create_instance_backup>

Creates a new backup.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<create_instance_file>

Creates a new file in the instance.

=over

=item C<name>: string, required

=item C<path>: string, optional

=item C<project>: string, optional

=item C<body>: raw_file, optionalsee Spec



=back

=item * B<create_instance_metadata_template>

Creates a new image template file for the instance.

=over

=item C<name>: string, required

=item C<path>: string, optional

=item C<project>: string, optional

=item C<body>: raw_file, optionalsee Spec



=back

=item * B<create_instance_snapshot>

Creates a new snapshot.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<delete_instance>

Deletes a specific instance.

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

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<delete_instance_backup>

Deletes the instance backup.

=over

=item C<backup>: string, required

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<delete_instance_console>

Clears the console log buffer.

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<delete_instance_files>

Removes the file.

=over

=item C<name>: string, required

=item C<path>: string, optional

=item C<project>: string, optional



=back

=item * B<delete_instance_log>

Removes the log file.

=over

=item C<filename>: string, required

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<delete_instance_metadata_templates>

Removes the template file.

=over

=item C<name>: string, required

=item C<path>: string, optional

=item C<project>: string, optional



=back

=item * B<delete_instance_snapshot>

Deletes the instance snapshot.

=over

=item C<name>: string, required

=item C<snapshot>: string, required

=item C<project>: string, optional



=back

=item * B<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.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<instance>

Gets a specific instance (basic struct).

Updates the instance configuration or trigger a snapshot restore.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<instance_backup>

Gets a specific instance backup.

=over

=item C<backup>: string, required

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<instance_backup_export>

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

=over

=item C<backup>: string, required

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<instance_backups>

Returns a list of instance backups (URLs).

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<instance_backups_recursion1>

Returns a list of instance backups (structs).

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<instance_console>

Gets the console log for the instance.

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<instance_files>

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

=over

=item C<name>: string, required

=item C<path>: string, optional

=item C<project>: string, optional



=back

=item * B<instance_log>

Gets the log file.

=over

=item C<filename>: string, required

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<instance_logs>

Returns a list of log files (URLs).

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<instance_metadata>

Gets the image metadata for the instance.

Updates the instance image metadata.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<instance_metadata_templates>

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

=over

=item C<name>: string, required

=item C<path>: string, optional

=item C<project>: string, optional



=back

=item * B<instance_recursion1>

Gets a specific instance (full struct).

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

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<instance_snapshot>

Gets a specific instance snapshot.

Updates the snapshot config.

=over

=item C<name>: string, required

=item C<snapshot>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<instance_snapshots>

Returns a list of instance snapshots (URLs).

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<instance_snapshots_recursion1>

Returns a list of instance snapshots (structs).

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<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.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<instances>

Returns a list of instances (URLs).

Changes the running state of all instances.

=over

=item C<all-projects>: boolean, optional

=item C<filter>: string, optional

=item C<project>: string, optional

=item C<body>: state, optional

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



=back

=item * B<instances_recursion1>

Returns a list of instances (basic structs).

=over

=item C<all-projects>: boolean, optional

=item C<filter>: string, optional

=item C<project>: string, optional



=back

=item * B<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.

=over

=item C<all-projects>: boolean, optional

=item C<filter>: string, optional

=item C<project>: string, optional



=back

=item * B<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.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<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.

=over

=item C<name>: string, required

=item C<snapshot>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<modify_instance>

Updates a subset of the instance configuration

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<modify_instance_metadata>

Updates a subset of the instance image metadata.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<modify_instance_snapshot>

Updates a subset of the snapshot config.

=over

=item C<name>: string, required

=item C<snapshot>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<rename_instance_backup>

Renames an instance backup.

=over

=item C<backup>: string, required

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back



=back

=head2 Metrics

=over

=item * B<metrics>

Gets metrics of instances.

=over

=item C<project>: string, optional



=back



=back

=head2 Network ACLs

=over

=item * B<create_network_acl>

Creates a new network ACL.

=over

=item C<project>: string, optional

=item C<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



=back

=item * B<delete_network_acl>

Removes the network ACL.

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<modify_network_acl>

Updates a subset of the network ACL configuration.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<network_acl>

Gets a specific network ACL.

Updates the entire network ACL configuration.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<network_acl_log>

Gets a specific network ACL log entries.

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<network_acls>

Returns a list of network ACLs (URLs).

=over

=item C<project>: string, optional



=back

=item * B<network_acls_recursion1>

Returns a list of network ACLs (structs).

=over

=item C<project>: string, optional



=back

=item * B<rename_network_acl>

Renames an existing network ACL.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back



=back

=head2 Network Forwards

=over

=item * B<create_network_forward>

Creates a new network address forward.

=over

=item C<networkName>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<delete_network_forward>

Removes the network address forward.

=over

=item C<listenAddress>: string, required

=item C<networkName>: string, required

=item C<project>: string, optional



=back

=item * B<modify_network_forward>

Updates a subset of the network address forward configuration.

=over

=item C<listenAddress>: string, required

=item C<networkName>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<network_forward>

Gets a specific network address forward.

Updates the entire network address forward configuration.

=over

=item C<listenAddress>: string, required

=item C<networkName>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<network_forward_recursion1>

Returns a list of network address forwards (structs).

=over

=item C<networkName>: string, required

=item C<project>: string, optional



=back

=item * B<network_forwards>

Returns a list of network address forwards (URLs).

=over

=item C<networkName>: string, required

=item C<project>: string, optional



=back



=back

=head2 Network Peers

=over

=item * B<create_network_peer>

Initiates/creates a new network peering.

=over

=item C<networkName>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<delete_network_peer>

Removes the network peering.

=over

=item C<networkName>: string, required

=item C<peerName>: string, required

=item C<project>: string, optional



=back

=item * B<modify_network_peer>

Updates a subset of the network peering configuration.

=over

=item C<networkName>: string, required

=item C<peerName>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<network_peer>

Gets a specific network peering.

Updates the entire network peering configuration.

=over

=item C<networkName>: string, required

=item C<peerName>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<network_peer_recursion1>

Returns a list of network peers (structs).

=over

=item C<networkName>: string, required

=item C<project>: string, optional



=back

=item * B<network_peers>

Returns a list of network peers (URLs).

=over

=item C<networkName>: string, required

=item C<project>: string, optional



=back



=back

=head2 Network Zones

=over

=item * B<create_network_zone>

Creates a new network zone.

=over

=item C<project>: string, optional

=item C<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



=back

=item * B<create_network_zone_record>

Creates a new network zone record.

=over

=item C<zone>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<delete_network_zone>

Removes the network zone.

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<delete_network_zone_record>

Removes the network zone record.

=over

=item C<name>: string, required

=item C<zone>: string, required

=item C<project>: string, optional



=back

=item * B<modify_network_zone>

Updates a subset of the network zone configuration.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<modify_network_zone_record>

Updates a subset of the network zone record configuration.

=over

=item C<name>: string, required

=item C<zone>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<network_zone>

Gets a specific network zone.

Updates the entire network zone configuration.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<network_zone_record>

Gets a specific network zone record.

Updates the entire network zone record configuration.

=over

=item C<name>: string, required

=item C<zone>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<network_zone_records>

Returns a list of network zone records (URLs).

=over

=item C<zone>: string, required

=item C<project>: string, optional



=back

=item * B<network_zone_records_recursion1>

Returns a list of network zone records (structs).

=over

=item C<zone>: string, required

=item C<project>: string, optional



=back

=item * B<network_zones>

Returns a list of network zones (URLs).

=over

=item C<project>: string, optional



=back

=item * B<network_zones_recursion1>

Returns a list of network zones (structs).

=over

=item C<project>: string, optional



=back



=back

=head2 Networks

=over

=item * B<create_network>

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

=over

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<delete_network>

Removes the network.

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<modify_network>

Updates a subset of the network configuration.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<network>

Gets a specific network.

Updates the entire network configuration.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<networks>

Returns a list of networks (URLs).

=over

=item C<project>: string, optional



=back

=item * B<networks_leases>

Returns a list of DHCP leases for the network.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<networks_recursion1>

Returns a list of networks (structs).

=over

=item C<project>: string, optional



=back

=item * B<networks_state>

Returns the current network state information.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<rename_network>

Renames an existing network.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back



=back

=head2 Operations

=over

=item * B<delete_operation>

Cancels the operation if supported.

=over

=item C<id>: string, required



=back

=item * B<operation>

Gets the operation state.

=over

=item C<id>: string, required



=back

=item * B<operation_wait>

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

=over

=item C<id>: string, required

=item C<timeout>: integer, optional



=back

=item * B<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.

=over

=item C<id>: string, required

=item C<secret>: string, optional

=item C<timeout>: integer, optional



=back

=item * B<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.

=over

=item C<id>: string, required

=item C<secret>: string, optional



=back

=item * B<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.

=over

=item C<id>: string, required

=item C<secret>: string, optional



=back

=item * B<operations>

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

=over



=back

=item * B<operations_recursion1>

Returns a list of operations (structs).

=over

=item C<project>: string, optional



=back



=back

=head2 Profiles

=over

=item * B<create_profile>

Creates a new profile.

=over

=item C<project>: string, optional

=item C<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



=back

=item * B<delete_profile>

Removes the profile.

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<modify_profile>

Updates a subset of the profile configuration.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<profile>

Gets a specific profile.

Updates the entire profile configuration.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back

=item * B<profiles>

Returns a list of profiles (URLs).

=over

=item C<project>: string, optional



=back

=item * B<profiles_recursion1>

Returns a list of profiles (structs).

=over

=item C<project>: string, optional



=back

=item * B<rename_profile>

Renames an existing profile.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<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



=back



=back

=head2 Projects

=over

=item * B<create_project>

Creates a new project.

=over

=item C<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



=back

=item * B<delete_project>

Removes the project.

=over

=item C<name>: string, required



=back

=item * B<modify_project>

Updates a subset of the project configuration.

=over

=item C<name>: string, required

=item C<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



=back

=item * B<project>

Gets a specific project.

Updates the entire project configuration.

=over

=item C<name>: string, required

=item C<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



=back

=item * B<project_state>

Gets a specific project resource consumption information.

=over

=item C<name>: string, required



=back

=item * B<projects>

Returns a list of projects (URLs).

=over



=back

=item * B<projects_recursion1>

Returns a list of projects (structs).

=over



=back

=item * B<rename_project>

Renames an existing project.

=over

=item C<name>: string, required

=item C<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



=back



=back

=head2 Server

=over

=item * B<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.

=over



=back

=item * B<events>

Connects to the event API using websocket.

=over

=item C<project>: string, optional

=item C<type>: string, optional



=back

=item * B<modify_server>

Updates a subset of the server configuration.

=over

=item C<target>: string, optional

=item C<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



=back

=item * B<resources>

Gets the hardware information profile of the LXD server.

=over

=item C<target>: string, optional



=back

=item * B<server>

Shows the full server environment and configuration.

Updates the entire server configuration.

=over

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<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.

=over



=back



=back

=head2 Storage

=over

=item * B<create_storage_pool>

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

=over

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<create_storage_pool_volume>

Creates a new storage volume.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<create_storage_pool_volumes_backup>

Creates a new storage volume backup.

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<create_storage_pool_volumes_snapshot>

Creates a new storage volume snapshot.

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<create_storage_pool_volumes_type>

Creates a new storage volume (type specific endpoint).

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<delete_storage_pool_volume_type>

Removes the storage volume.

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<delete_storage_pool_volumes_type_backup>

Deletes a new storage volume backup.

=over

=item C<backup>: string, required

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<delete_storage_pool_volumes_type_snapshot>

Deletes a new storage volume snapshot.

=over

=item C<name>: string, required

=item C<snapshot>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<delete_storage_pools>

Removes the storage pool.

=over

=item C<name>: string, required

=item C<project>: string, optional



=back

=item * B<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.

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<modify_storage_pool>

Updates a subset of the storage pool configuration.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<modify_storage_pool_volume_type>

Updates a subset of the storage volume configuration.

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<modify_storage_pool_volumes_type_snapshot>

Updates a subset of the storage volume snapshot configuration.

=over

=item C<name>: string, required

=item C<snapshot>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<rename_storage_pool_volumes_type_backup>

Renames a storage volume backup.

=over

=item C<backup>: string, required

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<rename_storage_pool_volumes_type_snapshot>

Renames a storage volume snapshot.

=over

=item C<name>: string, required

=item C<snapshot>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<storage_pool>

Gets a specific storage pool.

Updates the entire storage pool configuration.

=over

=item C<name>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<storage_pool_resources>

Gets the usage information for the storage pool.

=over

=item C<name>: string, required

=item C<target>: string, optional



=back

=item * B<storage_pool_volume_type>

Gets a specific storage volume.

Updates the entire storage volume configuration.

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<storage_pool_volume_type_state>

Gets a specific storage volume state (usage data).

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<storage_pool_volumes>

Returns a list of storage volumes (URLs).

=over

=item C<name>: string, required

=item C<filter>: string, optional

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<storage_pool_volumes_recursion1>

Returns a list of storage volumes (structs).

=over

=item C<name>: string, required

=item C<filter>: string, optional

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<storage_pool_volumes_type>

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

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<storage_pool_volumes_type_backup>

Gets a specific storage volume backup.

=over

=item C<backup>: string, required

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<storage_pool_volumes_type_backup_export>

Download the raw backup file from the server.

=over

=item C<backup>: string, required

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<storage_pool_volumes_type_backups>

Returns a list of storage volume backups (URLs).

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<storage_pool_volumes_type_backups_recursion1>

Returns a list of storage volume backups (structs).

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<storage_pool_volumes_type_recursion1>

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

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<storage_pool_volumes_type_snapshot>

Gets a specific storage volume snapshot.

Updates the entire storage volume snapshot configuration.

=over

=item C<name>: string, required

=item C<snapshot>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional

=item C<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



=back

=item * B<storage_pool_volumes_type_snapshots>

Returns a list of storage volume snapshots (URLs).

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<storage_pool_volumes_type_snapshots_recursion1>

Returns a list of storage volume snapshots (structs).

=over

=item C<name>: string, required

=item C<type>: string, required

=item C<volume>: string, required

=item C<project>: string, optional

=item C<target>: string, optional



=back

=item * B<storage_pools>

Returns a list of storage pools (URLs).

=over

=item C<project>: string, optional



=back

=item * B<storage_pools_recursion1>

Returns a list of storage pools (structs).

=over

=item C<project>: string, optional



=back



=back

=head2 Warnings

=over

=item * B<delete_warning>

Removes the warning.

=over

=item C<uuid>: string, required



=back

=item * B<modify_warning>

Updates a subset of the warning status.

=over

=item C<uuid>: string, required

=item C<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



=back

=item * B<warning>

Gets a specific warning.

Updates the warning status.

=over

=item C<uuid>: string, required

=item C<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



=back

=item * B<warnings>

Returns a list of warnings.

=over

=item C<project>: string, optional



=back

=item * B<warnings_recursion1>

Returns a list of warnings (structs).

=over

=item C<project>: string, optional



=back



=back



=head1 PSEUDO OBJECT ORIENTATION

Just for the sake of experimentation, I added a sub-package C<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:

=over

=item * C<restart>

=item * C<start>

=item * C<freeze>

=item * C<unfreeze>

=item * C<stop>

=item * C<state>

=back

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


=head1 EXAMPLES

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

=head1 SEE ALSO

=over

=item * L<Linux::LXC>

uses actually the existing lxc client to get the information

=item * L<https://github.com/jipipayo/Linux-REST-LXD>

pretty old, never persued

=back


=head1 HINTS

=over

=item * 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, L<you can run your own small CA, generate a .crt and .key for a client, and then
add it to lxd to trust it|https://serverfault.com/questions/882880/authenticate-to-lxd-rest-api-over-network-certificate-auth-keeps-failing>.

More on this topic is L<here|https://linuxcontainers.org/lxd/docs/master/authentication/>

=item * 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 C<sha256$> (no blanks) when you pass it to C<SSL_fingerprint>.

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

=back

=head1 ISSUES

Open issues are probably best put onto L<Github|https://github.com/drrrho/net-async-webservice-lxd>

=head1 AUTHOR

Robert Barta, C<< <rho at devc.at> >>

=head1 CREDITS

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

=head1 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:

L<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.
