libvirt: virt-login-shell
Description: libvirt, virtualization, virtualization API

# virt-login-shell

## tool to execute a shell within a container

Contents

- SYNOPSIS
- DESCRIPTION
- OPTIONS
- CONFIG
- EXIT STATUS
- BUGS
- AUTHOR
- COPYRIGHT
- LICENSE
- SEE ALSO

# SYNOPSIS

`virt-login-shell` [OPTION]

# DESCRIPTION

The `virt-login-shell` program is a setuid shell that is used to join an LXC container that matches the user's name. If the container is not running, `virt-login-shell` will attempt to start the container. `virt-login-shell` is not allowed to be run by root. Normal users will get added to a container that matches their username, if it exists, and they are configured in `/etc/libvirt/virt-login-shell.conf`.

The basic structure of most `virt-login-shell` usage is:

    virt-login-shell

# OPTIONS

`-c CMD`

Instruct the shell to run CMD instead of presenting an interactive shell prompt.

`-h`, `--help`

Display command line help usage then exit.

`-V`, `--version`

Display version information then exit.

# CONFIG

By default, `virt-login-shell` will execute the `/bin/sh` program for the user. You can modify this behaviour by defining the shell variable in `/etc/libvirt/virt-login-shell.conf`. e.g.

    shell = [ "/bin/bash" ]

If the `auto_shell` config option is set then it will attempt to automatically detect the shell from `/etc/password` inside the container. This should only be done if the container has a separate `/etc` directory from the host, otherwise it will end up recursively invoking `virt-login-shell`. e.g.

    auto_shell = 1

By default no users are allowed to use virt-login-shell, if you want to allow certain users to use virt-login-shell, you need to modify the allowed_users variable in /etc/libvirt/virt-login-shell.conf. e.g.

    allowed_users = [ "tom", "dick", "harry" ]

# EXIT STATUS

`virt-login-shell` normally returns the exit status of the command it executed. If the command was killed by a signal, but that signal is not fatal to virt-login-shell, then it returns the signal number plus 128.

Exit status generated by `virt-login-shell` itself:

- `0` An option was used to learn more about this binary.
- `125` Generic error before attempting execution of the configured shell; for example, if libvirtd is not running.
- `126` The configured shell exists but could not be executed.
- `127` The configured shell could not be found.

# BUGS

Please report all bugs you discover. This should be done via either:

1. the mailing list

   https://libvirt.org/contact.html

2. the bug tracker

   https://libvirt.org/bugs.html

Alternatively, you may report bugs to your software distributor / vendor.

# AUTHOR

Daniel Walsh

# COPYRIGHT

Copyright (C) 2013-2014 Red Hat, Inc., and the authors listed in the libvirt AUTHORS file.

# LICENSE

`virt-login-shell` is distributed under the terms of the GNU LGPL v2+. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE

# SEE ALSO

virsh(1), https://libvirt.org/