sbuild::session Class Reference

Session handler. More...

#include <sbuild-session.h>

Inheritance diagram for sbuild::session:

Inheritance graph
[legend]
Collaboration diagram for sbuild::session:

Collaboration graph
[legend]
List of all members.

Public Types

typedef custom_error< error_codeerror
 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:
Generated on Mon Sep 11 23:20:00 2006 for schroot by  doxygen 1.4.7