Provided by: makejail_0.0.5-9_all bug

NAME

       makejail -- Helps creating and maintaining a chroot jail

SYNOPSIS

       makejail [configuration_file]

Overview

       The  objective  of  makejail  is  to help an administrator creating and
       updating a chroot jail with short configuration files.

       Makejails attempts to  guess  and  install  into  the  jail  all  files
       required by the daemon.

       You have to understand how it works to configure it efficiently.

Detailed mechanism

       The list of these files is built from several sources:

       - the main method is to trace what files the daemon attempts to access,
       add them into the jail and restart  again  until  no  further  file  is
       found.

       - a list of files manually given in the configuration file.

       -  the  files which belongs to a package and eventually the packages it
       requires.

       When a file is added into the jail:

       - the shared libraries it needs (given by ldd) are added too.

       - upper directories are created if needed.

       - if the file is a symbolic link, the target is added too.

       - all the checks to determine what files a file needs are recursive.

       - all files  are  copied  maintaining  the  originals'  ownerships  and
       permissions.

       Some files are handled with a special method:

       - when the file is below /proc, the procfs filesystem is mounted inside
       the jail.

       - when the file is a socket, it's not copied.

       - when the file is the shared library cache, it's not copied,  ldconfig
       is run at the end.

       The steps of makejail are:

       - eventually remove the files in the jail first.

       -  if  you  specified some packages, add all the files which belongs to
       them.

       - if you specified some paths to include, add the files matching  these
       patterns.

       -  start  the daemon inside the jail, and trace it with strace, add the
       files it attempts to open which exist outside the  jail,  kill  it  and
       start again until no more file is found.

       -  start  the  daemon  inside the jail, and trace it while running some
       test processes outside the jail, see with strace what files the  daemon
       attempts to open.

Configuration files

       The  file  must be written in a correct python syntax. The good news is
       that the syntax is simple, and you can  eventually  write  some  python
       code to define the syntax.

       Some  default directives may be defined in /etc/makejail/makejail.conf,
       the configuration file given on the command line has predecence.

       All paths you use in the configuration file must be absolute.

Configuration directives - Basics

       Defaults  won't  work,  you  must  define  specific  values  for  these
       directives.

       chroot    The  path  to  the  chroot. The directory must exist and have
                 correct permissions and ownerships.

                 Format: "/path/to/jail"

                 Default: None

       testCommandsInsideJail
                 The commands used to start the daemon, a good starting  point
                 may be the command used in the startup script in /etc/init.d

                 Format: ["command1", "command2"]

                 Default: []

       processNames
                 The  name of the runnning processes after the daemon has been
                 started.

                 Format: ["process1", "process2"]

                 Default: []

Configuration directives - Tests

       After the daemon itself has been chrooted successfully,  some  commands
       can be executed from outside the jail to test the daemon.

       testCommandsOutsideJail
                 The test commands which should be executed.

                 Format: ["command1", "command2"]

                 Default: []

       promptForInteractiveTests
                 Whether  makejail  should  pause so you can stress the daemon
                 yourself.

                 Use only if makejail is run interactively, and don't redirect
                 its outputs.

                 Format: 1 (prompt) or 0 (don't prompt)

                 Default: 0

       promptForSomeMoreTests=0
                 Whether  makejail  should  loop while running tests until you
                 tell it it's over.

                 Use only if makejail is run interactively, and don't redirect
                 its outputs.

                 Format: 1 (prompt) or 0 (don't prompt)

                 Default: 0

       maxExecutions
                 Maximum   number  of  times  a  command  is  executed  before
                 aborting.

                 Format: integer

                 Default: 100

Configuration directives - Copying files

       doNotCopy Do not copy the files matching these  patterns  according  to
                 the rules used by the Unix shell.

                 No  tilde  expansion  is done, but *, ?, and character ranges
                 expressed with [] will be correctly matched.

                 Format: ["path1", "path2"]

                 Default:        ["/usr/share/doc",         "/usr/share/info",
                 "/usr/share/man", "/etc/fstab", "/etc/mtab", "/proc"]

       forceCopy When  initializing  the  jail,  copy the files matching these
                 patterns according to the rules used by the Unix shell.

                 No tilde expansion is done, but *, ?,  and  character  ranges
                 expressed with [] will be correctly matched.

                 Format: ["path1", "path2"]

                 Default: []

       cleanJailFirst
                 Whether makejail should remove files in jail first.

                 Format: 0 to do nothing or 1 to remove files from the jail.

                 Default: 0

       preserve  Useful  only if cleanJailFirst=1, makejail won't remove files
                 or directories if their path begins with one of  the  strings
                 in this list.

                 When  updating  a  jail,  you  should  for  example  put  the
                 locations of log files here.

                 Format: ["path1", "path2"]

                 Default: []

       maxRemove Useful only if  cleanJailFirst=1,  makejail  aborts  if  it's
                 about to remove more than this number of files from the jail.

                 This  may prevent makejail from erasing unwanted files if you
                 wrote chroot="/usr" or if you have mounted a partition in the
                 jail.

                 Format: integer

                 Default: 500

       users     Makejail  will  filter  the  files  listed  in  the directive
                 userFiles and copy only lines  matching  these  users,  which
                 means lines starting with "user:"

                 You  can  use  ["*"]  to disable filtering and copy the whole
                 file.

                 Format: ["user1", "user2"]

                 Default: []

       groups    Makejail will  filter  the  files  listed  in  the  directive
                 groupFiles  and  copy only lines matching these groups, which
                 means lines starting with "group:"

                 You can use ["*"] to disable filtering  and  copy  the  whole
                 file.

                 Format: ["group1", "group2"]

                 Default: []

Configuration directives - Timing

       These  times  are  in seconds, the values are the duration of sleeps at
       various stages of makejail.

       sleepAfterStartCommand
                 Duration of sleep after starting the daemon, after this delay
                 makejail considers it's in a correctly running state.

                 Format: floating number

                 Default: 2

       sleepAfterTest
                 Duration  of  sleep  after a test command has been run, after
                 this delay makejail considers the  daemon  has  finished  its
                 tasks related to this command.

                 Format: floating number

                 Default: 2

       sleepAfterKillall
                 Duration of sleep after killing the daemon processes.

                 Format: floating number

                 Default: 1

       sleepAfterStraceAttachPid
                 Duration of sleep after attaching strace to a running process
                 id.

                 Format: floating number

                 Default: 0.2

Configuration directives - Debian specific

       I initially thought with starting with  the  package  description,  but
       this method usually installs a bunch of files you won't need.

       packages  The  name  of  the  packages.  It  will  copy the files which
                 belongs   to   the   package   according    to    the    file
                 /var/lib/dpkg/info/$package.list.

                 Format: ["package1", "package2"]

                 Default: []

       useDepends
                 If  you  want  to also install other packages required by the
                 the initial list you specified.

                 It looks at the line "Depends:" in the  output  of  `dpkg  -p
                 $package`.

                 Format: 1 (use depends) or 0 (don't use depends)

                 Default: 0

       blockDepends
                 Useful  only if useDepends=1, it prevents the installation of
                 these packages even if dpkg says they are required.

                 Format: ["package1", "package2"]

                 Default: []

       debianDpkgInfoDir
                 Path to the dpkg $package.list files, "%s" will  be  replaced
                 by the name of the package.

                 Format: "/path/to/info/files/%s.list"

                 Default: "/var/lib/dpkg/info/%s.list"

Configuration directives - Paths so specific files and commands

       pathToLdConfig
                 Path  to the executable ldconfig, used to generate the shared
                 libraries  cache.  ldconfig  is  executed  in  the  jail   to
                 regenerate this cache.

                 Format: "/path/to/ldconfig"

                 Default:   "/sbin/ldconfig"  (Debian),  "/sbin/ldconfig.real"
                 (Ubuntu)

       pathToLdSoConf
                 The path to the configuration files used by  ldconfig,  which
                 says which directories should be scanned searching for shared
                 libraries.

                 Set this to None if your system doesn't use such a file.

                 Format: "/path/to/ld.so.conf"

                 Default: "/etc/ld.so.conf"

       pathToLdSoCache
                 The path to the shared libraries cache generated by ldconfig.

                 Format: "/path/to/ld.so.cache"

                 Default: "/etc/ld.so.cache"

       procPath  The path to the procfs filesystem.

                 Format: "/path/to/proc"

                 Default: "/proc"

       userFiles List of the files whose contents should be filtered, to  keep
                 only the users listed in the directive "users".

                 Format: ["file1", "file2]

                 Default: ["/etc/passwd", "/etc/shadow"]

       groupFiles
                 List  of the files whose contents should be filtered, to keep
                 only the groups listed in the directive "groups".

                 Format: ["file1", "file2]

                 Default:["/etc/group", "/etc/gshadow"]

       tempDir   The temporary directory where makejail  can  write  temporary
                 files.

                 There   may   be   a   lot   of   files   generated  here  if
                 keepStraceOutputs=1.

                 Format: "/temp/directory"

                 Default: "/tmp/makejail_logs"

       psCommand The command line used to list running processes.

                 The output must include the pid and the name of the process.

                 Format: "ps [options]"

                 Default: "ps -e"

       psColumns In which columns of the output of psCommand are the  ids  and
                 the name of the processes.

                 Spaces separate the columns, the first column is numbered 1.

                 Format: (columnPid,columnProcessName)

                 Default: [1,4]

Configuration directives - Commands to run to trace processes

       Here  you  can  configure  the  commands  which  must  be  run to trace
       processes. These are called strace though you can use another  program,
       like ktrace on OpenBSD.

       The  defaults  should  be suitable for systems using strace. "-f" means
       strace should trace process children too. Though it's  interested  only
       in  file  accesses,  it  doesn't  use "-e trace=file" because with this
       option it doesn't catch calls for "bind" and "connect" to sockets.

       straceCommand
                 String describing the strace command when executing a command
                 line.  "%command" will be replaced by the command to execute,
                 and "%file" by the path to the temporary trace file.

                 Format: "strace_command [options] %command > %file"

                 Default: "strace -e trace=file,connect -e signal=none -f  -ff
                 -o %file %command >/dev/null 2>&1"

       straceCommandPid
                 String describing the strace command when attaching itself to
                 a running process. "%pid" will be replaced by the id  of  the
                 process  to  trace,  and "%file" by the path to the temporary
                 trace file.

                 Format: "strace -e trace=file,connect -e signal=none  -f  -ff
                 -o %file -p %pid >/dev/null 2>&1"

                 Default: "strace -f -p %pid >/dev/null 2>>%file"

        straceCommandStop
                 Command to execute to stop the tracing.

                 Format: "strace_stop_command"

                 Default: "killall -9 strace"

       straceCommandView
                 Set  this  to  None  if  the  trace  output files can be read
                 directly, or the command line to  execute  which  prints  the
                 trace on stdout. "%file" will be replaced by the name of this
                 file.

                 Format: "strace_command_viewer [options] %file"

                 Default: None

       keepStraceOutputs
                 Whether makejail should remove the outputs of strace from the
                 directory tempDir.

                 Format: 0 (to remove the files) or 1 (to keep them)

                 Default: 0

Configuration directives - Patterns in the trace outputs

       These are three patterns which should match failed attempts to access a
       file in the traces.

       You must define a group (between parenthesis) which will be matched  by
       the path of the file.

       The  syntax  of  the  regular  expressions  in python is detailed here:
       http://py-howto.sourceforge.net/regex/regex.html

       If the match on a line means it is a failed attempt only  if  the  next
       line  matches  another  expression  (typically  a return code, no group
       needed), you can use an array of two strings instead of one string, the
       first  string  is  the  main  expression,  and  the  second  one is the
       expression which must match the next line. See  global.OpenBSD  in  the
       examples directory.

       stracePatterns
                 Regular expressions to detect a failed attempt at accessing a
                 file.

                 If the file exists outside the jail  makejail  will  copy  it
                 into the jail.

                 Format:  ["regexp1",  "regexp2", ["regexp3", "regexp3 for the
                 next line"]]

                 Default: ['.*("([ "]*)",.*) .* ENOENT .*']

       straceCreatePatterns
                 Regular expressions to detect a failed attempt at creating  a
                 file.

                 If  the  directory  where  the  file should be created exists
                 outside the jail, it will create it inside the jail.

                 Format: ["regexp1", "regexp2", ["regexp3", "regexp3  for  the
                 next line"]]

                 Default:  ['.*("([  "]*)",.*O_CREAT.*) .* ENOENT .*','bind(.*
                 path="([ "]*)".* ENOENT .*']

       straceSocketPatterns
                 Regular expressions to detect a failed attempt at accessing a
                 socket.

                 makejail  can't  create  the  socket,  it  will  just print a
                 warning.

                 Format: ["regexp1", "regexp2", ["regexp3", "regexp3  for  the
                 next line"]]

                 Default: ['connect(.* path="([ "]*)".* ENOENT .*']

AUTHOR

       This manual page was written by Alain Tesio, alain@onesite.org

       This software comes with no warranty.

REPORTING BUGS

       Makejail  is heavily patched for Debian systems.  If you are using this
       program as part of the Debian distribution you should  report  bugs  to
       the  Debian  Bug Tracking System using submit@bugs.debian.org. For this
       you  can  use   the   reportbug   or   bug   program.    Please,   read
       /usr/share/doc/debian/bug-reporting.txt (or www.debian.org/Bugs) before
       doing so.

       If  you  want  to  report  bugs  to   the   upstream   maintainer   use
       makejail@floc.net

                                                                   MAKEJAIL(8)