Provided by: pseudo_1.9.0+git20230301+ec6151a2b057-1_amd64 bug

NAME

       pseudo - run a command in a virtual root environment

SYNOPSIS

       pseudo [-dflv] [ -x flags ] [ -P prefix ] [ -rR root ] [ -t timeout ] [command]

       pseudo -h

       pseudo [-dflv] [ -x flags ] [ -P prefix ] [-BC] -i path

       pseudo [-dflv] [ -x flags ] [ -P prefix ] [-BC] -m from -M to

       pseudo [-dflv] [ -x flags ] [ -P prefix ] -S

       pseudo [-dflv] [ -x flags ] [ -P prefix ] -V

DESCRIPTION

       The  pseudo  utility  provides  a  virtual  root environment, hereafter referred to as the
       pseudo environment, allowing the creation of file system  images  and  packages  by  users
       without  root  privileges.   The  pseudo  environment  is implemented by pushing a special
       library (libpseudo.so) into the LD_PRELOAD environment variable.  This library  intercepts
       a  large  number  of common filesystem operations and some user-id related operations, and
       returns values that look as though the operations had been performed by a root user.  This
       is  in  turn  managed by a daemon program which keeps a list of virtualized file ownership
       and permissions; this daemon program itself is pseudo.

       The pseudo program itself can also be used as a program launcher.  The launcher is used to
       automatically  configure  a  working  environment,  then  execute  processes  within  that
       environment.  Alternatively, you  can  bypass  this  by  setting  up  certain  environment
       variables  (see  the ENVIRONMENT section below).  The pseudo client library (libpseudo.so)
       can then start the server automatically.

       The pseudo command can be invoked in one of several possible modes:

       -B      The -B option causes pseudo to scan its database,  as  with  the  -C  option,  but
               instead  of  reporting  mismatches, pseudo attempts to repair them.  Specifically,
               device and inode  number  mismatches  are  corrected,  and  symlink  or  directory
               mismatches result in deletion of database entries.

       -C      The  -C  option  causes  pseudo  to  scan  its  database,  comparing  against  the
               filesystem, and reporting likely errors.  This may be unreliable when  the  server
               is actively running.

       -h      The -h option causes pseudo to print a usage message and exit.

       -i      The  -i  option  causes  pseudo  to attempt to correct device number mismatches by
               checking inodes; if path has the same inode number as recorded  in  the  database,
               but  a different device number, all instances of the device number recorded in the
               database are updated to the device number in the live filesystem for  path.   This
               is  intended  to  handle  the  mismatches  that  can  occur when remounting an NFS
               filesystem.  The -i option implies the -C option.  You can  also  specify  the  -B
               option to request that the database be rebuilt.

       -m      The -m and -M options cause pseudo to rename files, replacing the string from with
               the string to.  The -m option pair implies the -C option.  You  can  also  specify
               the -B option to request that the database be rebuilt.

       -V      The   -V  option  causes  pseudo  to  print  configuration  information  and  exit
               immediately.

       -S      The -S option causes pseudo to try to find an existing server,  and  if  it  finds
               one,  instructs  that server to shut down as soon as all clients are detached from
               it.  Note that the server will not shut down while clients are connected to it; in
               this case, pseudo will print a list of the remaining client PIDs.

       -d      The  -d  option causes pseudo to immediately detach and run in the background as a
               daemon.  This is rarely useful except for debugging.

       Finally,  invoked  without  any  of  these  options,  pseudo  sets  up  an  emulated  root
       environment,  then  invokes command if it was provided, otherwise a shell (using the SHELL
       environment variable if it is set, or /bin/sh otherwise).

       The following options modify the behavior of pseudo:

       -d (daemonize)
               Run as a daemon; pseudo detaches from  the  calling  environment  and  runs  as  a
               daemon.   The  command  returns  successfully  if  this appears to have succeeded,
               otherwise it produces an error message and returns a failure status.

       -f (foreground)
               Run in the foreground; pseudo runs as a server, and does not try  to  start  other
               commands.  This mode is useful for debugging.

       -l (log)
               Enable  logging.   The  pseudo daemon will log every filesystem transaction in the
               log database.

       -r root

       -R root Set the PSEUDO_CHROOT environment variable, running  as  though  the  program  had
               called  chroot(2)  on  the  specified  path.   With  -r, this implies changing the
               working directory to the specified directory; with -R, it does not.

       -t timeout
               Set the timeout of the pseudo daemon, in seconds.  The  default  is  currently  30
               seconds.   After  this long with no attached clients, the pseudo daemon shuts down
               automatically.  The server never shuts down while it has attached  clients.   Note
               that  this  does  not prevent continued use; new clients can restart the daemon if
               they need it.

       -v (verbose)
               Increase the verbosity of the pseudo  daemon,  and  the  client  library  for  any
               programs  started by this invocation of pseudo.  This is equivalent to the numeric
               form of the PSEUDO_DEBUG environment variable; multiple -v  options  increase  the
               debugging level.

       -x (debug)
               Set  specific  deugging flags (the pseudo utility's help message lists them). This
               is equivalent to the string form of the PSEUDO_DEBUG environment variable.

EXAMPLES

       The two most common usages of pseudo are using it to run specific commands, and setting up
       an environment manually for running various other commands.

       For the first case, the usage is reasonably simple:

       $ /path/to/pseudo
       # commands which require root privileges

       You  may have to use the -Pprefix option to tell pseudo where to look for its database and
       server.  If you specify a full path, pseudo assumes that PSEUDO_PREFIX should be the  path
       to  the  directory  containing the pseudo program, or to the /bin directory containing the
       pseudo program.

       The other way to use pseudo is by setting up an environment.  This is suitable for use  in
       Makefiles  or  similar  environments,  where  you  want to run a series of commands in the
       pseudo environment, but not to keep invoking the pseudo command.  To do this, set  up  the
       PSEUDO_PREFIX, LD_PRELOAD, and LD_LIBRARY_PATH  environment  variables,  then run programs
       normally.  You do not need to separately invoke the  pseudo  daemon;  the  client  library
       starts it as needed.

       If  you  have  moved  a  directory  which  pseudo was tracking, you may be able to get the
       database reattached using the -m option.  A typical usage might be:

       $ /path/to/pseudo -B -m oldpath -M newpath

       This requests that pseudo replace the string  oldpath  with  the  string  newpath  at  the
       beginnings  of  filenames,  then  regenerate  the  database,  correcting  any device/inode
       numbers.

DIAGNOSTICS

       Depending on invocation, diagnostic messages usually go either to standard error or to the
       file PSEUDO_PREFIX /var/pseudo/pseudo.log.  By default, pseudo daemon messages go into the
       log file, but messages generated by the client code go to standard error.   These  can  be
       changed  using  the PSEUDO_DEBUG_FILE environment variable, documented in ENVIRONMENT.  At
       the default logging level, only critical messages are displayed.  If you have  raised  the
       logging  level  (using the -v option or the PSEUDO_DEBUG environment variable), additional
       messages are displayed.  Levels higher than 2 are very unlikely to be  useful  outside  of
       pseudo development.

       Diagnostic  messages  seen  by  default  are those which are believed to indicate either a
       serious internal flaw in pseudo or a completely unexpected  failure  from  the  underlying
       operating system.  In normal use, you should see no diagnostic messages.

ENVIRONMENT

       The  most significant environment variables for pseudo are LD_PRELOAD and LD_LIBRARY_PATH.
       However, these variables have no special meaning to pseudo; rather, they are used  in  the
       standard  way  to manipulate the dynamic linker into loading the libpseudo library so that
       it can intercept calls into the underlying C library.

       The following environment variables are used directly by pseudo:

       PSEUDO_BINDIR
               This directory holds the path to the pseudo binary; by  default,  it  is  the  bin
               directory under PSEUDO_PREFIX.

       PSEUDO_CHROOT
               This  variable holds the current emulated chroot(2) path.  Paths that are relative
               to this are treated as though they were instead relative to the filesystem root.

       PSEUDO_DEBUG
               This variable holds either a numeric "debug level" for pseudo to run at, or a  set
               of  specific  debugging  flags,  generally  letters.   Use  pseudo  -h  to see the
               available flags. In general, this is useful only for debugging pseudo itself.

       PSEUDO_DEBUG_FILE
               The name of a file to use for debugging  messages  from  the  pseudo  client;  the
               default  is  to  log  to standard error.  If the string contains a single %s, that
               string is replaced with the short program name, and if it contains  a  single  %d,
               that  string is replaced with the process ID.  Other format specifiers (other than
               '%%') are not allowed.  By default, the pseudo server logs to the file  pseudo.log
               in the var/pseudo directory, while clients log to standard error.

       PSEUDO_DISABLED
               If  this  variable is set to a value that doesn't look like f, F, n, N, s, S, or a
               numeric zero, the pseudo client library does not modify  the  behavior  of  called
               functions,  though  it  continues  to  intercept  them  and  block  signals  while
               processing them.  This variable is reevaluated on every call to  fork(2), clone(2)
               or  related  functions.  If the value starts with a lowercase or uppercase s , the
               pseudo client disables all server spawning and communications, but still  operates
               locally.  This  means  that no filesystem mode or permissions changes are actually
               recorded or reported, but functions like chown() will still report  success,  even
               though  nothing  happens.  This function is intended for debugging of issues which
               are complicated by the server's involvement.

       PSEUDO_ALLOW_FSYNC
               If this variable is set, pseudo will allow fsync() and related system calls,  even
               it  was  configured  with  the --enable-force-async option. Otherwise, that option
               results in all such calls being discarded silently, even when  PSEUDO_DISABLED  is
               set. The value specified doesn't matter.

       PSEUDO_ENOSYS_ABORT
               If  this  variable  is  set,  the  pseudo client library calls abort() rather than
               setting errno to ENOSYS in the event of a call to a missing  underlying  function.
               This variable has no function outside of debugging pseudo itself.

       PSEUDO_LIBDIR
               This  directory  holds  the path to the pseudo shared libraries; by default, it is
               the lib directory under PSEUDO_PREFIX.  (On 64-bit hosts, lib64 is also used.)

       PSEUDO_LOCALSTATEDIR
               This directory holds the pseudo database files and log files; by  default,  it  is
               the var/pseudo directory under PSEUDO_PREFIX.

       PSEUDO_NOSYMLINKEXP
               By  default, when chrooted, pseudo prepends the chroot directory to the paths used
               for absolute symlinks;  this  behavior  ensures  that  opening  symlinks  produces
               expected  results in most cases.  In some cases you may want to suppress this.  If
               this variable is unset, or set to any value other than 0, pseudo  expands  symlink
               paths like this.  If this variable is set to 0, the behavior is disabled.

       PSEUDO_OPTS
               This  variable  holds  options  to  be  passed  to any new pseudo servers started.
               Typically, when pseudo is used as a launcher,  this  will  be  set  automatically;
               however, you can also use it to pass options when using LD_PRELOAD to manually run
               things in the pseudo environment.

       PSEUDO_PASSWD
               This variable holds the path to a directory containing password and group files to
               use  for  emulation of various password and group routines.  It should be the path
               to a directory containing the etc directory  containing  files  named  passwd  and
               group.   When  pseudo  is  emulating a chroot environment, the chroot directory is
               used by preference.  The parallelism between these  cases  is  why  this  variable
               points  at  the  parent  directory of etc rather than the directory containing the
               files. If there is no chroot environment, and this variable is also unset,  pseudo
               falls  back to a directory specified at configure time, with the default being the
               root directory. This is controlled by the PSEUDO_PASSWD_FALLBACK definition.

       PSEUDO_PREFIX
               If set, the variable PSEUDO_PREFIX is used to determine the path to  use  to  find
               the   pseudo   server,  in  PSEUDO_PREFIX/bin,  and  the  pseudo  data  files,  in
               PSEUDO_PREFIX/var/pseudo.  This  variable  is  automatically  set  by  the  pseudo
               program when it is used as a launcher.

       PSEUDO_PROFILE_PATH
               If  pseudo  was  configured  with  profiling enabled, specifies a path in which to
               write client profiling information for use with the  pseudo_profile  utility  (not
               built by default).

       PSEUDO_TAG
               If  this  variable  is set in a client's environment, its value is communicated to
               the server at the beginning of each  client  session,  and  recorded  in  the  log
               database  if any logging occurs related to a specific client.  Note that different
               clients may have different tags associated with them; the tag value is per-client,
               not per-server.

       PSEUDO_UIDS, PSEUDO_GIDS
               These variables are used internally to pass information about the current emulated
               user and group identity from one process to another.

       PSEUDO_UNLOAD
               This variable  is  reevaluated  on  every  call  to  fork(2), exec(3)  or  related
               functions.   If  the  variable exists libpseudo.so will be removed from LD_PRELOAD
               and PSEUDO_DISABLED behavior will also be triggered.  For  processes  that  simply
               fork(2),  the  behavior  will  be the same as if PSEUDO_DISABLED was set.  For new
               processes, after a call to exec(3) or system(3) pseudo will not be loaded  in  the
               new process.

       SHELL   If  set,  this will be used when pseudo is invoked without either a command or one
               of the options which directs  it  to  do  something  other  than  run  a  command.
               Otherwise, pseudo defaults to /bin/sh .

BUGS

       The  pseudo database is not particularly robust in the face of whole directory trees being
       moved, or changes in the underlying device and inode numbers.  It has a reasonable  chance
       of  recovering  if  only  the  path  or  the  device  numbers  have changed, but it is not
       particularly designed to address this.  A future release  is  expected  to  have  improved
       resilience in these cases.

       The filesystem on which pseudo keeps its database and files must at a minimum support UNIX
       domain sockets and reasonable file locking semantics.  Note that pseudo relies on flock(2)
       locking  semantics;  a  lock  has  to  persist into a child process.  This should probably
       eventually be fixed.

       The pseudo client library is probably thread-safe, but has not been adequately  tested  or
       debugged in that context.

       Filesystem  performance  is  noticably  worse  under pseudo than it is otherwise.  This is
       probably because nearly every operation (other than reads and writes)  involves  at  least
       one  round-trip  network communication with the server, and probably some kind of database
       activity.

SEE ALSO

       fakeroot(1), ld.so(8), pseudolog(1), sqlite3(1)

FURTHER READING

       Documentation of the internals of pseudo may be found  in  the  doc  subdirectory  of  the
       pseudo source tree.

                                  pseudo - pretending to be root                        pseudo(1)