How to access files in an instance¶
You can manage files inside an instance using the LXD client or the API without needing to access the instance through the network. Files can be individually edited or deleted, pushed from or pulled to the local machine. Alternatively, if you’re using the LXD client, you can mount the instance’s file system onto the local machine.
Note
The UI does not currently support accessing files in an instance.
For containers, these file operations always work and are handled directly by LXD.
For virtual machines, the lxd-agent
process must be running inside of the virtual machine for them to work.
Edit instance files¶
To edit an instance file from your local machine, enter the following command:
lxc file edit <instance_name>/<path_to_file>
For example, to edit the /etc/hosts
file in the instance, enter the following command:
lxc file edit my-instance/etc/hosts
Note
The file must already exist on the instance.
You cannot use the edit
command to create a file on the instance.
There is no API endpoint that lets you edit files directly on an instance. Instead, you need to pull the content of the file from the instance, edit it, and then push the modified content back to the instance.
Delete files from the instance¶
To delete a file from your instance, enter the following command:
lxc file delete <instance_name>/<path_to_file>
Send the following DELETE request to delete a file from your instance:
lxc query --request DELETE /1.0/instances/<instance_name>/files?path=<path_to_file>
See DELETE /1.0/instances/{name}/files
for more information.
Pull files from the instance to the local machine¶
To pull a file from your instance to your local machine, enter the following command:
lxc file pull <instance_name>/<path_to_file> <local_file_path>
For example, to pull the /etc/hosts
file to the current directory, enter the following command:
lxc file pull my-instance/etc/hosts .
Instead of pulling the instance file into a file on the local system, you can also pull it to stdout and pipe it to stdin of another command. This can be useful, for example, to check a log file:
lxc file pull my-instance/var/log/syslog - | less
To pull a directory with all contents, enter the following command:
lxc file pull -r <instance_name>/<path_to_directory> <local_location>
Send the following request to pull the contents of a file from your instance to your local machine:
lxc query --request GET /1.0/instances/<instance_name>/files?path=<path_to_file>
You can then write the contents to a local file, or pipe them to stdin of another command.
For example, to pull the contents of the /etc/hosts
file and write them to a my-instance-hosts
file in the current directory, enter the following command:
lxc query --request GET /1.0/instances/my-instance/files?path=/etc/hosts > my-instance-hosts
To examine a log file, enter the following command:
lxc query --request GET /1.0/instances/<instance_name>/files?path=<file_path> | less
To pull the contents of a directory, send the following request:
lxc query --request GET /1.0/instances/<instance_name>/files?path=<path_to_directory>
This request returns a list of files in the directory, and you can then pull the contents of each file.
See GET /1.0/instances/{name}/files
for more information.
Push files from the local machine to the instance¶
To push a file from your local machine to your instance, enter the following command:
lxc file push <local_file_path> <instance_name>/<path_to_file>
You can specify the file permissions by adding the --gid
, --uid
, and --mode
flags.
To push a directory with all contents, enter the following command:
lxc file push -r <local_location> <instance_name>/<path_to_directory>
Send the following request to write content to a file on your instance:
lxc query --request POST /1.0/instances/<instance_name>/files?path=<path_to_file> --data <content>
See POST /1.0/instances/{name}/files
for more information.
To push content directly from a file, you must use a tool that can send raw data from a file, which lxc query
does not support.
For example, with curl:
curl -X POST -H "Content-Type: application/octet-stream" --data @<local_file_path> \
--unix-socket /var/snap/lxd/common/lxd/unix.socket \
lxd/1.0/instances/<instance_name>/files?path=<path_to_file>
Mount a file system from the instance¶
You can mount an instance file system into a local path on your client.
To do so, make sure that you have sshfs
installed.
Then run the following command (note that if you’re using the snap, the command requires root permissions):
lxc file mount <instance_name>/<path_to_directory> <local_location>
You can then access the files from your local machine.
Set up an SSH SFTP listener
Alternatively, you can set up an SSH SFTP listener. This method allows you to connect with any SFTP client and with a dedicated user name. Also, if you’re using the snap, it does not require root permission.
To do so, first set up the listener by entering the following command:
lxc file mount <instance_name> [--listen <address>:<port>]
For example, to set up the listener on a random port on the local machine (for example, 127.0.0.1:45467
):
lxc file mount my-instance
If you want to access your instance files from outside your local network, you can pass a specific address and port:
lxc file mount my-instance --listen 192.0.2.50:2222
Caution
Be careful when doing this, because it exposes your instance remotely.
To set up the listener on a specific address and a random port:
lxc file mount my-instance --listen 192.0.2.50:0
The command prints out the assigned port and a user name and password for the connection.
Tip
You can specify a user name by passing the --auth-user
flag.
Use this information to access the file system.
For example, if you want to use sshfs
to connect, enter the following command:
sshfs <user_name>@<address>:<path_to_directory> <local_location> -p <port>
For example:
sshfs [email protected]:/home my-instance-files -p 35147
You can then access the file system of your instance at the specified location on the local machine.
Mounting a file system is not directly supported through the API, but requires additional processing logic on the client side.