mirror of
https://github.com/lxc/incus
synced 2026-08-02 05:26:46 +00:00
110 lines
4.1 KiB
Markdown
110 lines
4.1 KiB
Markdown
(run-commands)=
|
|
# How to run commands in an instance
|
|
|
|
Incus allows to run commands inside an instance using the Incus client, without needing to access the instance through the network.
|
|
|
|
For containers, this always works and is handled directly by Incus.
|
|
For virtual machines, the `incus-agent` process must be running inside of the virtual machine for this to work.
|
|
|
|
To run commands inside your instance, use the [`incus exec`](incus_exec.md) command.
|
|
By running a shell command (for example, `/bin/bash`), you can get shell access to your instance.
|
|
|
|
## Run commands inside your instance
|
|
|
|
To run a single command from the terminal of the host machine, use the [`incus exec`](incus_exec.md) command:
|
|
|
|
incus exec <instance_name> -- <command>
|
|
|
|
For example, enter the following command to update the package list on your container:
|
|
|
|
incus exec debian-container -- apt-get update
|
|
|
|
### Execution mode
|
|
|
|
Incus can execute commands either interactively or non-interactively.
|
|
|
|
In interactive mode, a pseudo-terminal device (PTS) is used to handle input (stdin) and output (stdout, stderr).
|
|
This mode is automatically selected by the CLI if connected to a terminal emulator (and not run from a script).
|
|
To force interactive mode, add either `--force-interactive` or `--mode interactive` to the command.
|
|
|
|
In non-interactive mode, pipes are allocated instead (one for each of stdin, stdout and stderr).
|
|
This method allows running a command and properly getting separate stdin, stdout and stderr as required by many scripts.
|
|
To force non-interactive mode, add either `--force-noninteractive` or `--mode non-interactive` to the command.
|
|
|
|
### User, groups and working directory
|
|
|
|
Incus has a policy not to read data from within the instances or trust anything that can be found in the instance.
|
|
Therefore, Incus does not parse files like `/etc/passwd`, `/etc/group` or `/etc/nsswitch.conf` to handle user and group resolution.
|
|
|
|
As a result, Incus doesn't know the home directory for the user or the supplementary groups the user is in.
|
|
|
|
By default, Incus runs commands as `root` (UID 0) with the default group (GID 0) and the working directory set to `/root`.
|
|
You can override the user, group and working directory by specifying absolute values through the following flags:
|
|
|
|
- `--user` - the user ID for running the command
|
|
- `--group` - the group ID for running the command
|
|
- `--cwd` - the directory in which the command should run
|
|
|
|
### Environment
|
|
|
|
You can pass environment variables to an exec session in the following two ways:
|
|
|
|
Set environment variables as instance options
|
|
: To set the `ENVVAR` environment variable to `VALUE` in the instance, set the `environment.ENVVAR` instance option (see {config:option}`instance-miscellaneous:environment.*`):
|
|
|
|
incus config set <instance_name> environment.ENVVAR=VALUE
|
|
|
|
Pass environment variables to the exec command
|
|
: To pass an environment variable to the exec command, use the `--env` flag.
|
|
For example:
|
|
|
|
incus exec <instance_name> --env ENVVAR=VALUE -- <command>
|
|
|
|
In addition, Incus sets the following default values (unless they are passed in one of the ways described above):
|
|
|
|
```{list-table}
|
|
:header-rows: 1
|
|
|
|
* - Variable name
|
|
- Condition
|
|
- Value
|
|
* - `PATH`
|
|
- \-
|
|
- Concatenation of:
|
|
- `/usr/local/sbin`
|
|
- `/usr/local/bin`
|
|
- `/usr/sbin`
|
|
- `/usr/bin`
|
|
- `/sbin`
|
|
- `/bin`
|
|
- `/snap` (if applicable)
|
|
- `/etc/NIXOS` (if applicable)
|
|
* - `LANG`
|
|
- \-
|
|
- `C.UTF-8`
|
|
* - `HOME`
|
|
- running as root (UID 0)
|
|
- `/root`
|
|
* - `USER`
|
|
- running as root (UID 0)
|
|
- `root`
|
|
```
|
|
|
|
## Get shell access to your instance
|
|
|
|
If you want to run commands directly in your instance, run a shell command inside it.
|
|
For example, enter the following command (assuming that the `/bin/bash` command exists in your instance):
|
|
|
|
incus exec <instance_name> -- /bin/bash
|
|
|
|
By default, you are logged in as the `root` user.
|
|
If you want to log in as a different user, enter the following command:
|
|
|
|
incus exec <instance_name> -- su --login <user_name>
|
|
|
|
```{note}
|
|
Depending on the operating system that you run in your instance, you might need to create a user first.
|
|
```
|
|
|
|
To exit the instance shell, enter `exit` or press `Ctrl`+`d`.
|
