- Main Page
- Namespaces
- Classes
- Files
- Directories
- Related Pages

- Class List
- Class Hierarchy
- Class Members

# sbuild::session Class Reference

Session handler. More...

`#include <sbuild-session.h>`

Inheritance diagram for sbuild::session:

[legend]
Collaboration diagram for sbuild::session:

[legend]
List of all members.

## Public Types
typedef custom_error< error_code > | error
| Exception type.
typedef std::tr1::shared_ptr< chroot_config > | config_ptr
| A shared_ptr to a chroot_config object.
typedef std::tr1::shared_ptr< session > | ptr
| A shared_ptr to a session object.
| OPERATION_AUTOMATIC
| Begin, end and run a session automatically.
| OPERATION_BEGIN
| Begin a session.
| OPERATION_RECOVER
| Recover an existing (but inactive) session.
| OPERATION_END
| End a session.
| OPERATION_RUN
| Run a command in an existing session.
| CHDIR
| Failed to change to directory.
| CHDIR_FB
| Falling back to directory.
| CHILD_CORE
| Child dumped core.
| CHILD_FAIL
| Child exited abnormally (reason unknown).
| CHILD_FORK
| Failed to fork child.
| CHILD_SIGNAL
| Child terminated by signal.
| CHILD_WAIT
| Wait for child failed.
| CHROOT
| Failed to change root to directory.
| CHROOT_ALIAS
| No chroot found matching alias.
| CHROOT_LOCK
| Failed to lock chroot.
| CHROOT_SETUP
| Setup failed.
| CHROOT_UNKNOWN
| Failed to find chroot.
| CHROOT_UNLOCK
| Failed to unlock chroot.
| COMMAND_ABS
| Command must have an absolute path.
| EXEC
| Failed to execute.
| GROUP_GET_SUP
| Failed to get supplementary groups.
| GROUP_GET_SUPC
| Failed to get supplementary group count.
| GROUP_SET
| Failed to set group.
| GROUP_SET_SUP
| Failed to set supplementary groups.
| GROUP_UNKNOWN
| Group not found.
| PAM
| PAM error.
| ROOT_DROP
| Failed to drop root permissions.
| SHELL
| Shell not available.
| SHELL_FB
| Falling back to shell.
| SIGNAL_CATCH
| Caught signal.
| SIGNAL_SET
| Failed to set signal handler.
| USER_SET
| Failed to set user.
| USER_SWITCH
| User switching is not permitted.
enum | operation { OPERATION_AUTOMATIC, OPERATION_BEGIN, OPERATION_RECOVER, OPERATION_END, OPERATION_RUN }
| Session operations. More...
enum | error_code { CHDIR, CHDIR_FB, CHILD_CORE, CHILD_FAIL, CHILD_FORK, CHILD_SIGNAL, CHILD_WAIT, CHROOT, CHROOT_ALIAS, CHROOT_LOCK, CHROOT_SETUP, CHROOT_UNKNOWN, CHROOT_UNLOCK, COMMAND_ABS, EXEC, GROUP_GET_SUP, GROUP_GET_SUPC, GROUP_SET, GROUP_SET_SUP, GROUP_UNKNOWN, PAM, ROOT_DROP, SHELL, SHELL_FB, SIGNAL_CATCH, SIGNAL_SET, USER_SET, USER_SWITCH }
| Error codes. More...
## Public Member Functions
| session (std::string const &service, config_ptr &config, operation operation, string_list const &chroots)
| The constructor.
virtual | ~session ()
| The destructor.
config_ptr const & | get_config () const
| Get the configuration associated with this session.
void | set_config (config_ptr &config)
| Set the configuration associated with this session.
string_list const & | get_chroots () const
| Get the chroots to use in this session.
void | set_chroots (string_list const &chroots)
| Set the chroots to use in this session.
operation | get_operation () const
| Get the operation this session will perform.
void | set_operation (operation operation)
| Set the operation this session will perform.
std::string const & | get_session_id () const
| Get the session identifier.
void | set_session_id (std::string const &session_id)
| Set the session identifier.
bool | get_force () const
| Get the force status of this session.
void | set_force (bool force)
| Set the force status of this session.
void | save_termios ()
| Save terminal state.
void | restore_termios ()
| Restore terminal state.
int | get_child_status () const
| Get the exit (wait) status of the last child process to run in this session.
virtual sbuild::auth::status | get_auth_status () const
| Check if authentication is required, taking users, groups, root-users and root-groups membership of all chroots specified into account.
## Protected Member Functions
virtual auth::status | get_chroot_auth_status (auth::status status, chroot::ptr const &chroot) const
| Check if authentication is required for a single chroot, taking users, groups, root-users and root-groups membership into account.
virtual void | run_impl ()
| Run a session.
virtual string_list | get_login_directories () const
| Get a list of directories to change to when running a login shell.
virtual string_list | get_command_directories () const
| Get a list of directories to change to when running a command Multiple directories are used as fallbacks.
virtual std::string | get_shell () const
| Get the shell to run.
virtual void | get_command (chroot::ptr &session_chroot, std::string &file, string_list &command) const
| Get the command to run.
virtual void | get_login_command (chroot::ptr &session_chroot, std::string &file, string_list &command) const
| Get the command to run a login shell.
virtual void | get_user_command (chroot::ptr &session_chroot, std::string &file, string_list &command) const
| Get the command to run a user command.
## Protected Attributes
std::string | cwd
| Current working directory.
## Private Member Functions
void | setup_chroot (chroot::ptr &session_chroot, chroot::setup_type setup_type)
| Setup a chroot.
void | run_chroot (chroot::ptr &session_chroot)
| Run command or login shell in the specified chroot.
void | run_child (chroot::ptr &session_chroot)
| Run a command or login shell as a child process in the specified chroot.
void | wait_for_child (pid_t pid, int &child_status)
| Wait for a child process to complete, and check its exit status.
void | set_sighup_handler ()
| Set the SIGHUP handler.
void | clear_sighup_handler ()
| Restore the state of SIGHUP prior to setting the handler.
void | set_sigterm_handler ()
| Set the SIGTERM handler.
void | clear_sigterm_handler ()
| Restore the state of SIGTERM prior to setting the handler.
void | set_signal_handler (int signal, struct sigaction *saved_signal, void(*handler)(int))
| Set a signal handler.
void | clear_signal_handler (int signal, struct sigaction *saved_signal)
| Restore the state of the signal prior to setting the handler.
## Private Attributes
config_ptr | config
| The chroot configuration.
string_list | chroots
| The chroots to run the session operation in.
int | chroot_status
| The current chroot status.
int | child_status
| The child exit status.
operation | session_operation
| The session operation to perform.
std::string | session_id
| The session identifier.
bool | force
| The session force status.
sigaction | saved_sighup_signal
| Signal saved while sighup handler is set.
sigaction | saved_sigterm_signal
| Signal saved while sigterm handler is set.
termios | saved_termios
| Saved terminal settings.
bool | termios_ok
| Are the saved terminal settings valid?

## Detailed Description

Session handler.

This class provides the session handling for schroot. It derives from auth, which performs all the necessary PAM actions, specialising it by overriding its virtual functions. This allows more sophisticated handling of user authorisation (users, groups, root-users and root-groups membership in the configuration file) and session management (setting up the session, entering the chroot and running the requested command or shell).

## Member Typedef Documentation

typedef std::tr1::shared_ptr<chroot_config> sbuild::session::config_ptr

A shared_ptr to a chroot_config object.

typedef custom_error<error_code> sbuild::session::error

Exception type.

Reimplemented from sbuild::auth.

typedef std::tr1::shared_ptr<session> sbuild::session::ptr

A shared_ptr to a session object.

## Member Enumeration Documentation

enum sbuild::session::error_code

Error codes.

Enumerator:

  CHDIR | Failed to change to directory.
  CHDIR_FB | Falling back to directory.
  CHILD_CORE | Child dumped core.
  CHILD_FAIL | Child exited abnormally (reason unknown).
  CHILD_FORK | Failed to fork child.
  CHILD_SIGNAL | Child terminated by signal.
  CHILD_WAIT | Wait for child failed.
  CHROOT | Failed to change root to directory.
  CHROOT_ALIAS | No chroot found matching alias.
  CHROOT_LOCK | Failed to lock chroot.
  CHROOT_SETUP | Setup failed.
  CHROOT_UNKNOWN | Failed to find chroot.
  CHROOT_UNLOCK | Failed to unlock chroot.
  COMMAND_ABS | Command must have an absolute path.
  EXEC | Failed to execute.
  GROUP_GET_SUP | Failed to get supplementary groups.
  GROUP_GET_SUPC | Failed to get supplementary group count.
  GROUP_SET | Failed to set group.
  GROUP_SET_SUP | Failed to set supplementary groups.
  GROUP_UNKNOWN | Group not found.
  PAM | PAM error.
  ROOT_DROP | Failed to drop root permissions.
  SHELL | Shell not available.
  SHELL_FB | Falling back to shell.
  SIGNAL_CATCH | Caught signal.
  SIGNAL_SET | Failed to set signal handler.
  USER_SET | Failed to set user.
  USER_SWITCH | User switching is not permitted.

Reimplemented from sbuild::auth.

enum sbuild::session::operation

Session operations.

Enumerator:

  OPERATION_AUTOMATIC | Begin, end and run a session automatically.
  OPERATION_BEGIN | Begin a session.
  OPERATION_RECOVER | Recover an existing (but inactive) session.
  OPERATION_END | End a session.
  OPERATION_RUN | Run a command in an existing session.

## Constructor & Destructor Documentation

session::session | ( | std::string const & | service,
|  | config_ptr & | config,
|  | operation | operation,
|  | string_list const & | chroots |
| ) |  |  |

The constructor.

Parameters:

  | service | the PAM service name.
  | config | a shared_ptr to the chroot configuration.
  | operation | the session operation to perform.
  | chroots | the chroots to act upon.

session::~session | ( |  | ) | `[virtual]`

The destructor.

Reimplemented in dchroot::session, and dchroot_dsa::session.

## Member Function Documentation

void session::clear_sighup_handler | ( |  | ) | `[private]`

Restore the state of SIGHUP prior to setting the handler.

void session::clear_signal_handler | ( | int | signal,
|  | struct sigaction * | saved_signal |
| ) |  |  | `[private]`

Restore the state of the signal prior to setting the handler.

Parameters:

  | signal | the signal number.
  | saved_signal | the location from which to restore the saved handler.

void session::clear_sigterm_handler | ( |  | ) | `[private]`

Restore the state of SIGTERM prior to setting the handler.

auth::status session::get_auth_status | ( |  | ) | const`[virtual]`

Check if authentication is required, taking users, groups, root-users and root-groups membership of all chroots specified into account.

Reimplemented from sbuild::auth.

int session::get_child_status | ( |  | ) | const

Get the exit (wait) status of the last child process to run in this session.

Returns:
  the exit status.

auth::status session::get_chroot_auth_status | ( | auth::status | status,
|  | chroot::ptr const & | chroot |
| ) |  |  | const`[protected, virtual]`

Check if authentication is required for a single chroot, taking users, groups, root-users and root-groups membership into account.

Reimplemented in dchroot::session, and dchroot_dsa::session.

string_list const & session::get_chroots | ( |  | ) | const

Get the chroots to use in this session.

Returns:
  a list of chroots.

void session::get_command | ( | chroot::ptr & | session_chroot,
|  | std::string & | file,
|  | string_list & | command |
| ) |  |  | const`[protected, virtual]`

Get the command to run.

Parameters:

  | session_chroot | the chroot to setup. This must be present in the chroot list and the chroot configuration object.
  | file | the filename to pass to execve(2).
  | command | the argv to pass to execve(2).

string_list session::get_command_directories | ( |  | ) | const`[protected, virtual]`

Get a list of directories to change to when running a command Multiple directories are used as fallbacks.

Returns:
  a list of directories

Reimplemented in dchroot::session_base.

session::config_ptr const & session::get_config | ( |  | ) | const

Get the configuration associated with this session.

Returns:
  a shared_ptr to the configuration.

bool session::get_force | ( |  | ) | const

Get the force status of this session.

Returns:
  true if operation will be forced, otherwise false.

void session::get_login_command | ( | chroot::ptr & | session_chroot,
|  | std::string & | file,
|  | string_list & | command |
| ) |  |  | const`[protected, virtual]`

Get the command to run a login shell.

Parameters:

  | session_chroot | the chroot to setup. This must be present in the chroot list and the chroot configuration object.
  | file | the filename to pass to execve(2).
  | command | the argv to pass to execve(2).

string_list session::get_login_directories | ( |  | ) | const`[protected, virtual]`

Get a list of directories to change to when running a login shell.

Multiple directories are used as fallbacks.

Returns:
  a list of directories

Reimplemented in dchroot::session, and dchroot_dsa::session.

session::operation session::get_operation | ( |  | ) | const

Get the operation this session will perform.

Returns:
  the operation.

std::string const & session::get_session_id | ( |  | ) | const

Get the session identifier.

The session identifier is a unique string to identify a session.

Returns:
  the session id.

std::string session::get_shell | ( |  | ) | const`[protected, virtual]`

Get the shell to run.

This finds a suitable shell to run in the chroot, falling back to /bin/sh if necessary. Note that it assumes it is inside the chroot when called.

Returns:
  the shell.

Reimplemented from sbuild::auth.

void session::get_user_command | ( | chroot::ptr & | session_chroot,
|  | std::string & | file,
|  | string_list & | command |
| ) |  |  | const`[protected, virtual]`

Get the command to run a user command.

Parameters:

  | session_chroot | the chroot to setup. This must be present in the chroot list and the chroot configuration object.
  | file | the filename to pass to execve(2).
  | command | the argv to pass to execve(2).

Reimplemented in dchroot::session, and dchroot_dsa::session.

void session::restore_termios | ( |  | ) |

Restore terminal state.

void session::run_child | ( | chroot::ptr & | session_chroot | ) | `[private]`

Run a command or login shell as a child process in the specified chroot.

This method is only ever to be run in a child process, and will never return.

Parameters:

  | session_chroot | the chroot to setup. This must be present in the chroot list and the chroot configuration object.

void session::run_chroot | ( | chroot::ptr & | session_chroot | ) | `[private]`

Run command or login shell in the specified chroot.

An error will be thrown on failure.

Parameters:

  | session_chroot | the chroot to setup. This must be present in the chroot list and the chroot configuration object.

void session::run_impl | ( |  | ) | `[protected, virtual]`

Run a session.

If a command has been specified, this will be run in each of the specified chroots. If no command has been specified, a login shell will run in the specified chroot.

An error will be thrown on failure.

Implements sbuild::auth.

Reimplemented in dchroot::session_base.

void session::save_termios | ( |  | ) |

Save terminal state.

void session::set_chroots | ( | string_list const & | chroots | ) |

Set the chroots to use in this session.

Parameters:

  | chroots | a list of chroots.

void session::set_config | ( | config_ptr & | config | ) |

Set the configuration associated with this session.

Parameters:

  | config | a shared_ptr to the configuration.

void session::set_force | ( | bool | force | ) |

Set the force status of this session.

Parameters:

  | force | true to force operation, otherwise false.

void session::set_operation | ( | operation | operation | ) |

Set the operation this session will perform.

Parameters:

  | operation | the operation.

void session::set_session_id | ( | std::string const & | session_id | ) |

Set the session identifier.

The session identifier is a unique string to identify a session.

Parameters:

  | session_id | the session id.

void session::set_sighup_handler | ( |  | ) | `[private]`

Set the SIGHUP handler.

An error will be thrown on failure.

void session::set_signal_handler | ( | int | signal,
|  | struct sigaction * | saved_signal,
|  | void(*)(int) | handler |
| ) |  |  | `[private]`

Set a signal handler.

An error will be thrown on failure.

Parameters:

  | signal | the signal number.
  | saved_signal | the location to save the current handler.
  | handler | the signal handler to install.

void session::set_sigterm_handler | ( |  | ) | `[private]`

Set the SIGTERM handler.

An error will be thrown on failure.

void session::setup_chroot | ( | chroot::ptr & | session_chroot,
|  | chroot::setup_type | setup_type |
| ) |  |  | `[private]`

Setup a chroot.

This runs all of the commands in setup.d or run.d.

The environment variables CHROOT_NAME, CHROOT_DESCRIPTION, CHROOT_LOCATION, AUTH_USER and AUTH_VERBOSITY are set for use in setup scripts. See schroot-setup(5) for a complete list.

An error will be thrown on failure.

Parameters:

  | session_chroot | the chroot to setup. This must be present in the chroot list and the chroot configuration object.
  | setup_type | the type of setup to perform.

void session::wait_for_child | ( | pid_t | pid,
|  | int & | child_status |
| ) |  |  | `[private]`

Wait for a child process to complete, and check its exit status.

An error will be thrown on failure.

Parameters:

  | pid | the pid to wait for.
  | child_status | the place to store the child exit status.

Todo:
  Use waitpid instead of wait.

## Member Data Documentation

int sbuild::session::child_status`[private]`

The child exit status.

int sbuild::session::chroot_status`[private]`

The current chroot status.

string_list sbuild::session::chroots`[private]`

The chroots to run the session operation in.

config_ptr sbuild::session::config`[private]`

The chroot configuration.

std::string sbuild::session::cwd`[protected]`

Current working directory.

bool sbuild::session::force`[private]`

The session force status.

struct sigaction sbuild::session::saved_sighup_signal`[private]`

Signal saved while sighup handler is set.

struct sigaction sbuild::session::saved_sigterm_signal`[private]`

Signal saved while sigterm handler is set.

struct termios sbuild::session::saved_termios`[private]`

Saved terminal settings.

std::string sbuild::session::session_id`[private]`

The session identifier.

operation sbuild::session::session_operation`[private]`

The session operation to perform.

bool sbuild::session::termios_ok`[private]`

Are the saved terminal settings valid?

The documentation for this class was generated from the following files:

- sbuild/sbuild-session.h
- sbuild/sbuild-session.cc