bk bkd(7.3ce)               BitKeeper User's Manual              bk bkd(7.3ce)

NAME
       bk bkd - the BitKeeper daemon

SYNOPSIS
       bk bkd [<options>]

DESCRIPTION
       The  BitKeeper  daemon, bkd, is used to synchronize and query reposito-
       ries.  It is typically run in one of the following ways:

       =>  automatically started when accessing a remote repository  via  rsh,
           ssh, HTTP, and/or the file system;
       =>  automatically started via ssh as a login shell;
       =>  manually started as a long running stand-alone daemon;
       =>  automatically started as a long running service at boot time.

       The  method used usually depends on how the remote repository is named.

       The stand-alone daemon method has no security, other than  the  ability
       to  run  in read-only mode and/or the ability to limit chdir.  If secu-
       rity is a requirement, use ssh to access the  daemon.   See  below  for
       information on configuring the daemon as a login shell.

ANONYMOUS ACCESS
       The  most  common use of the stand-alone daemon is for anonymous access
       to a repository.  To provide read-only, anonymous access, you can run:

           bk bkd -d -xpush

       This will allow anyone to read (but not write) all repositories  at  or
       below the directory in which the bkd was started.

       If  you  want to export a single repository, pick a port number, and do
       this:

           cd /home/bk/linux-2.6
           bk bkd -d -p5555 -xcd -xpush

       This says to run in daemon mode, bind to port 5555,  and  disallow  the
       "cd"  and "push" commands.  By disallowing the "cd" command, the daemon
       at port 5555 is tied to the repository in the current working directory
       (bkd  needs  to  be run at the root of the repository).  By disallowing
       the "push" command, the repository is protected from updates.

       Clients can get to this repository by using the BK URLs of

           bk://host.domain:5555
           http://host.domain:5555

       i.e.,

           $ bk clone bk://host.domain:5555 my_tree

       These HTTP URLs allow access through most  firewalls.   BitKeeper  sup-
       ports  accessing repositories through HTTP proxies, including authenti-
       cated proxies.

SECURED ACCESS VIA SSH
       Secure access is provided via ssh.  There two ways to invoke ssh:

       a)  [<user>@]<host>:<pathname>
       b)  ssh://[<user>@]<host>[:<port>][/<pathname>]

       Using either form, ssh will be called to run bk bkd on the remote host.
       When the client command completes, the ssh connection is broken and the
       bkd daemon goes away.

   BKD LOGIN SHELL
       To add security when using ssh, run the bk bkd as the login shell.

       On Red Hat Linux, the following steps are necessary to add a  BitKeeper
       daemon  login  shell:  create a simple shell script, call it bkd_login,
       put it someplace like /usr/libexec/bitkeeper/bkd_login,  add  the  full
       path  to  the  script  in /etc/shells, and add a user with that path as
       their shell.

       An example bkd_login shell script:

           #!/bin/sh
           exec bk bkd -C -xcd

       Note: using the bkd as a login shell when accessing  the  system  using
       rsh  is unsupported and is known not to work due to a long standing rsh
       bug.

BK/WEB
       The bkd is a self-contained HTTP server which provides the BK/Web  fea-
       ture of BitKeeper.

       To access the BK/Web interface, use a web browser to go to the URL:

           http://<host>:<port>/

       where  <port>  is  the port on which the bkd is listening (see the "-p"
       option, below).

WINDOWS BASED BKD
       It is possible to install a one or more bkd's as Windows services,  see

OPTIONS
       -C                This  option  provides a slightly more secure mode of
                         operation in that  the  bkd  will  refuse  to  change
                         directories  up  out of the directory in which it was
                         started.
       -d                Run as a daemon, typically in the background (but see
                         the next option).
       -D                Debug mode, do not fork and run in the background.
       -h                For all outgoing bk push, bk pull, and bk clone oper-
                         ations, wrap command responses in HTTP protocol.  Use
                         when bk bkd is called from a CGI script.
       -l<log>           Log  accesses  in  <log>;  if <log> is not specified,
                         then log to stderr.
       -P<pfile>         Write the pid of daemon process  into  this  file  at
                         startup.
       -p<addr>:[<port>]
       -p<port>          Specify  an  alternative  address  and/or  port.   By
                         default, the bkd allows connection requests from  any
                         host on port 0x3962 (aka 14690).  If <addr> is speci-
                         fied, the bkd will bind to that address, limiting the
                         hosts  which are allowed to connect.  The most common
                         usage is to bind to localhost (127.0.0.1) which means
                         that any local process may connect but no remote pro-
                         cesses  may  connect.   Note:  When   specifying   an
                         address,  the  trailing  colon  is required even when
                         <port> is omitted.  This option implies "-d".
       -i<cmd>           Include <cmd> from the by  default  excluded  command
                         list.
       -S                Run  in  "symlinks  are  allowed" safe mode.  This is
                         similar to -C, with the addition  of  allowing  paths
                         that  are  symlinks under the bkd root and resolve to
                         outside of the bkd root.  This is useful to  be  able
                         to run this sequence of commands:

                             mkdir /repos
                             ln -s /mnt/disk1/repos/myrepo /repos/myrepo
                             cd /repos
                             bk bkd -S
                             cd $HOME
                             bk clone bk://machine/myrepo

                         Note:  a  user  could check in a symlink to anywhere,
                         then push their repo to the master, then follow  that
                         symlink.   This  option  is  useful for organizations
                         where that is acceptable.
       -U                Run in "unsafe" mode.  Any non-interactive  BitKeeper
                         command  may  be run remotely.  The bkd runs the com-
                         mand at the request of a remote BitKeeper client.  If
                         the  client  does  not  have access to the machine on
                         which the bkd is running then this option allows  far
                         more  access  than  is usually prudent.  On the other
                         hand, if the client has remote  login  privileges  to
                         the machine (or if the client is on the same machine)
                         then there is no security issue  with  allowing  this
                         feature.  Accordingly, this option is turned on auto-
                         matically for any bkd started by the client  via  the
                         file://,  rsh://,  or ssh:// access methods.  If your
                         environment is secured then running a long lived  bkd
                         with  this option provides more BitKeeper functional-
                         ity to your users.
       -x<cmd>           Exclude <cmd> from the  allowed  command  list.   The
                         list of commands which may be excluded currently are:
                         abort, cd, check, clone, get,  httpget,  pull,  push,
                         pwd, rclone, rootkey, status, synckeys, and version.

EXAMPLES
       We  use  the following in /var/bitkeeper/repositories to provide anony-
       mous read only access to some BitKeeper repositories:

           #---------------------- cut here --------------------------
           nobody /home/bk/bk-3.2.x -C -xpush -p3200
           nobody /home/bk/bk-3.3.x -C -xpush -p3300
           #---------------------- cut here --------------------------

       The following init script is known to work on Red Hat Linux based  sys-
       tems.  The init script shown can be generated with a

           $ bk getmsg bitkeeper.init
           #---------------------- cut here --------------------------
           #!/bin/sh
           #
           # chkconfig: 2345 24 84
           # description: BitKeeper server

           # Source networking configuration.
           if [ -f /etc/sysconfig/network ]
           then . /etc/sysconfig/network

                # Check that networking is up.
                [ ${NETWORKING} = "no" ] && exit 0
           fi
           [ -x /usr/bin/bk ] || exit 0
           VAR=/var/bitkeeper

           case "$1" in
               start_msg) echo "Start BitKeeper daemons"
                     ;;
               stop_msg)  echo "Stop BitKeeper daemons"
                     ;;
               restart)   $0 stop
                          $0 start
                     ;;
               start)     cd $VAR || exit 1
                     test -f repositories || {
                          echo Nothing advertised
                          exit 0
                     }
                     while read user dir opts
                     do   (
                          cd $dir || exit 1
                          F=`basename $dir`
                          CMD="bk bkd -d $opts -l$VAR/log.$F -P$VAR/pid.$F"
                          su -c "$CMD" $user 2>> $VAR/errors
                          echo Started $CMD in $dir
                          )
                     done < repositories
                     ;;

               stop)
                     cd $VAR || exit 1
                     echo Shutting down BitKeeper daemons
                     for i in pid.*
                     do   kill `cat $i`
                          rm $i
                     done
                     ;;

               status)    cd $VAR || exit 1
                     for i in pid.*
                     do   echo This pid should be running: `cat $i`
                     done
                     ps -axf | grep bkd

                     ;;

               *)         echo "Usage: bitkeeper {start|stop}"
                     exit 1
                     ;;
           esac

           exit 0
           #---------------------- cut here --------------------------

BUGS/NOTES
       Needs ssh to provide access controlled, authenticated users.  One could
       argue that this is code reuse rather than a bug.

       BitKeeper does not ship ssh since it is widely available.

       On Windows the bkd service does not work when started  from  a  network
       drive.

       On  Windows  the bkd service does not work when started from a subst'ed
       drive.

SEE ALSO
       bk parent
       bk service
       bk url
       bk Howto-bkd

CATEGORY
       Repository
       Admin

BitKeeper Inc                         1E1                        bk bkd(7.3ce)