BK-BKD(1)

✨ NAME ✨

Okay bestie, meet bk bkd — the BitKeeper daemon, straight out of the BitKeeper User’s Manual. She’s the background baddie used to synchronize and query repositories, and she can show up in a bunch of different ways depending on how you call her 💅

---

🦋 SYNOPSIS 🦋

bk bkd [options]

---

💖 DESCRIPTION 💖

The BitKeeper daemon, bkd, is used to synchronize and query repositories. She’s typically run in one of these 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. See bk help url for details on the naming syntax.

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 security is a requirement, use ssh to access the daemon. See below for info 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 supports accessing repositories through HTTP proxies, including authenticated proxies.

---

🔐 SECURED ACCESS VIA SSH 🔐

Secure access is provided via ssh. There are 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 feature 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 one or more bkd’s as Windows services, see bk help service.

---

💅 OPTIONS 💅

• −C — slightly more secure mode: bkd will refuse to change directories up out of the directory in which it was started. She stays in her lane, periodt ✨
• −d — run as a daemon, typically in the background (but peek at the next option 👀).
• −D — debug mode: do not fork and do not run in the background.
• −h — for all outgoing bk push, bk pull, and bk clone operations, wrap command responses in HTTP protocol. Use when bk bkd is called from a CGI script.
• −llog — log accesses in log; if log is not specified, then log to stderr.
• −Ppfile — write the pid of the daemon process into this file at startup.
• −paddr:[port], −pport — 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 specified, 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 processes may connect. Note: when specifying an address, the trailing colon is required even when port is omitted. This option implies −d.
• −icmd — 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 command 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 automatically 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 functionality to your users.
• −xcmd — 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 anonymous 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 systems. 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

---

Brought to u by BitKeeper Inc, version 1E1, manual tag bk bkd(none) — catch u later, bestie 🫶💖✨