<commit_before>.so bk-macros
.TH "bk bkd" 1 20%E% "\*(BC" "\*(UM"
.SH NAME
bk bkd \- the \*(BK daemon
.SH SYNOPSIS
.Bc bk bkd [\-dDehi] [
.OPTreq \-L dir
.Bc ] [
.OPTreq \-l log
.Bc ] [
.OPTreq \-P pfile
.Bc ] [
.OPTreq \-p psrt
.Bc ] [
.OPTreq \-t num
.Bc ] [
.OPTreq \-u uid
.Bc ] [
.OPTreq \-x cmd
.B ]
.SH DESCRIPTION
.LP
The \*(BK daemon, bkd, is used to get information about a
repository from a remote machine.  It is run in one of three ways,
.sp
.RS .5i
a) via rsh/ssh, i.e., "rsh remote host bk bkd -e",
.br
b) via ssh as a login shell, and/or
.br
c) as a stand-alone daemon, i.e., "bkd \-d".
.RE
.LP
The method used depends on how the remote repository is named.
See 
.B bk parent
for details on the naming syntax.
.LP
The preferred method is via ssh, since ssh provides a secure channel.
.LP
The stand-alone daemon method has no security, other than the
ability to run in read-only mode.  The daemon does support compression.
If security is a requirement, use 
.B ssh
to get to the daemon.  See below for configuring the daemon as a login
shell.
.SH COMMANDS
.LP
\*(BK client programs interact with the daemon directly using
the following commands. These commands are not intended for user
access, however, it may be useful to access the commands directly
for debugging.  When debugging, telnet to the \*(BK port and issue
the commands.
.LP
The command summary is below.  The options tend to track the client
commands fairly closely.
.sp
.RS .5i
cd pathname
.br
clone [\-q] [\-z[0\-9]]
.br
get /filename HTTP/1.0
.br
help
.br
pull [\-lnq] [\-z[0\-9]]
.br
push [\-q] [\-z[0\-9]]
.br
pwd
.br
rootkey
.br
status [\-v]
.br
version
.RE
.LP
The client commands parse their options, connect to the server, and
send the appropriate commands to complete the action.  When started
with the \-l option, all sent commands are logged.
.SH "ANONYMOUS ACCESS"
.LP
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:
.DS
bk bkd \-d \-xpush
.DE
.LP
This will allow anyone to read (but not write) all repositories on the
system running the daemon.
.LP
If you want to export a single repository, pick a port number, and 
do this:
.DS
cd /u/linux
bk bkd \-d \-p5555 \-xcd \-xpush
.DE
.LP
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.
.LP
Clients can get to this repository by using the BK URL of
.DS    
bk://host.domain:5555
.DE
.br
i.e.,
.DS
$ bk clone bk://host.domain:5555 my_tree
.DE
.SH SECURED ACCESS VIA SSH
Secure access is provided via 
.BR ssh .
There two ways to invoke 
.BR ssh :
.tp .5i
a)
when the repository is specified in this form: 
[\c
.ARGc user @]
.ARGc host :
.ARG pathname ,
.B ssh
will be called to run
.B bk bkd -e
on the remote host.  When the client command completes, the 
.B ssh 
connection is broken and the 
.B bkd
daemon goes away.
.tp
b)
when the repository is specified in this form: 
.Bc bk://user@host[
.ARG pathname \fB]\fR,
.B ssh
will be called to remote login to 
.B host
and will expect that the login shell is the \*(BK daemon.
.LP
.SS BKD LOGIN SHELL
On Red Hat Linux, the following steps are necessary to add a \*(BK 
daemon login shell:
create a simple shell script, call it 
.BR bkd , 
put it someplace like 
.BR /usr/libexec/bitkeeper/bkd ,
add the full path to the script in 
.BR /etc/shells ,
and add a user with that path as their shell.
.LP
An example 
.B bkd
shell script which works for us is:
.DS
#!/bin/sh
exec bk bkd -e
.DE
.LP
.B Note:
this does not work with 
.BR rsh ,
but it is somewhat pointless to have 
.B rsh 
work since it is insecure.
.SH OPTIONS
.TP 1i
.B \-d
Run as a daemon.
.tp
.B \-D
Debug mode, do not fork and run in the background.
.tp
.B \-e
Exit on any error.
.tp
.B \-h
Make bkd print http headers on all outgoing bk push, bk pull,
and bk clone messages.  Use when bkd is run in a cgi environment.
.tp
.B \-i
Interactive, provide prompts.
.tp
.OPTreq \-L dir
Specify the directory under which one or more logging repositories can
be stored.  
.tp
.OPTreq \-l log
Log accesses in 
.ARG log ;
if
.ARG log
is not specified, then log to stderr.
.tp
.OPTreq \-P pfile
Write the pid of daemon process into this file at startup.
.tp
.OPTreq \-p port
Specify an alternative port.  The default port is currently
0x3962 (aka 14690) but that will change once we get a
reserved port. 
.tp
.OPTreq \-t num
Exit after 
.ARG num
seconds. (used when debugging)
.tp
.OPTreq \-u uid
Run as UID
.ARG uid .
.tp
.OPTreq \-x cmd
Exclude 
.ARG cmd
from the allowed command list.
.SH EXAMPLES
.LP
We use the following in 
.B /var/bitkeeper/repositories
to provide anonymous read only access to some \*(BK repositories.  
.DS
#----------------------\ cut\ here\ --------------------------
/home/bk/LMbench \-p5000 \-xcd \-xpush \-u99
/home/bk/bitcluster \-p6000 \-xcd \-xpush \-u99
/home/bk/one \-p7000 \-xcd \-xpush \-u99
#----------------------\ cut\ here\ --------------------------
.DE
.LP
The init script shown below can be generated with a 
.DS
$ bk getmsg bitkeeper.init
.DE
We use the it in
.BR /etc/rc.d/init.d/bitkeeper
to start up \*(BK on bitkeeper.com (a Red Hat based Linux system):
.DS
#----------------------\ cut\ here\ --------------------------
#!/bin/sh
#
# bitkeeper	Start/stop the bitkeeper daemon.
# 		@(#)bitkeeper.init 1.1 Copyright (c) 2000 <NAME>

# 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"
		;;
    start)	cd $VAR || exit 1
		test \-f repositories || {
			echo Nothing advertised
			exit 0
		}
		while read dir opts
		do	(
			cd $dir || exit 1
			F=`basename $dir`
			bk bkd $opts \-l$VAR/log.$F \-P$VAR/pid.$F
			echo Started bkd $opts in $dir
			)
		done < repositories
		;;

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

    status)	ps \-axf | grep bkd
		;;

    *)		echo "Usage: bitkeeper {start|stop}"
		exit 1
		;;
esac
exit 0
#----------------------\ cut\ here\ --------------------------
.DE
.SH BUGS
Needs 
.B ssh
to provide access controlled, authenticated users.
One could argue that this is code reuse rather than a bug.
.LP
\*(BM
does not ship
.B ssh
since it is export controlled.
.SH "SEE ALSO"
.SA parent
.SA Howto-bkd 1
.\" help://anonymous
.\" help://deamon
.\" help://daemon
.\" help://demon
.\" help://security
.SH CATEGORY
.B Repository
.br
.B Admin
<commit_msg>more minor man fixes.<commit_after>.so bk-macros
.TH "bk bkd" 1 20%E% "\*(BC" "\*(UM"
.SH NAME
bk bkd \- the \*(BK daemon
.SH SYNOPSIS
.Bc bk bkd [\-dDehi] [
.OPTreq \-L dir
.Bc ] [
.OPTreq \-l log
.Bc ] [
.OPTreq \-P pfile
.Bc ] [
.OPTreq \-p psrt
.Bc ] [
.OPTreq \-t num
.Bc ] [
.OPTreq \-u uid
.Bc ] [
.OPTreq \-x cmd
.B ]
.SH DESCRIPTION
.LP
The \*(BK daemon, bkd, is used to get information about a
repository from a remote machine.  It is run in one of three ways,
.sp
.RS .5i
a) via rsh/ssh, i.e., "rsh remote host bk bkd -e",
.br
b) via ssh as a login shell, and/or
.br
c) as a stand-alone daemon, i.e., "bkd \-d".
.RE
.LP
The method used depends on how the remote repository is named.
See 
.B bk parent
for details on the naming syntax.
.LP
The preferred method is via ssh, since ssh provides a secure channel.
.LP
The stand-alone daemon method has no security, other than the
ability to run in read-only mode.  The daemon does support compression.
If security is a requirement, use 
.B ssh
to get to the daemon.  See below for configuring the daemon as a login
shell.
.SH COMMANDS
.LP
\*(BK client programs interact with the daemon directly using
the following commands. These commands are not intended for user
access, however, it may be useful to access the commands directly
for debugging.  When debugging, telnet to the \*(BK port and issue
the commands.
.LP
The command summary is below.  The options tend to track the client
commands fairly closely.
.sp
.RS .5i
cd pathname
.br
clone [\-q] [\-z[0\-9]]
.br
get /filename HTTP/1.0
.br
help
.br
pull [\-lnq] [\-z[0\-9]]
.br
push [\-q] [\-z[0\-9]]
.br
pwd
.br
rootkey
.br
status [\-v]
.br
version
.RE
.LP
The client commands parse their options, connect to the server, and
send the appropriate commands to complete the action.  When started
with the \-l option, all sent commands are logged.
.SH "ANONYMOUS ACCESS"
.LP
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:
.DS
bk bkd \-d \-xpush
.DE
.LP
This will allow anyone to read (but not write) all repositories on the
system running the daemon.
.LP
If you want to export a single repository, pick a port number, and 
do this:
.DS
cd /u/linux
bk bkd \-d \-p5555 \-xcd \-xpush
.DE
.LP
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.
.LP
Clients can get to this repository by using the BK URL of
.DS    
bk://host.domain:5555
.DE
.br
i.e.,
.DS
$ bk clone bk://host.domain:5555 my_tree
.DE
.SH SECURED ACCESS VIA SSH
Secure access is provided via 
.BR ssh .
There two ways to invoke 
.BR ssh :
.tp .5i
a)
when the repository is specified in this form: 
[\c
.ARGc user @]
.ARGc host :
.ARG pathname ,
.B ssh
will be called to run
.B bk bkd -e
on the remote host.  When the client command completes, the 
.B ssh 
connection is broken and the 
.B bkd
daemon goes away.
.tp
b)
when the repository is specified in this form: 
.Bc bk://user@host[
.ARG pathname \fB]\fR,
.B ssh
will be called to remote login to 
.B host
and will expect that the login shell is the \*(BK daemon.
.LP
.SS BKD LOGIN SHELL
On Red Hat Linux, the following steps are necessary to add a \*(BK 
daemon login shell:
create a simple shell script, call it 
.BR bkd , 
put it someplace like 
.BR /usr/libexec/bitkeeper/bkd ,
add the full path to the script in 
.BR /etc/shells ,
and add a user with that path as their shell.
.LP
An example 
.B bkd
shell script which works for us is:
.DS
#!/bin/sh
exec bk bkd -e
.DE
.LP
.B Note:
this does not work with 
.BR rsh ,
but it is somewhat pointless to have 
.B rsh 
work since it is insecure.
.SH OPTIONS
.TP 1i
.B \-d
Run as a daemon.
.tp
.B \-D
Debug mode, do not fork and run in the background.
.tp
.B \-e
Exit on any error.
.tp
.B \-h
Make bkd print http headers on all outgoing bk push, bk pull,
and bk clone messages.  Use when bkd is run in a cgi environment.
.tp
.B \-H
Do not share port.  Run bkd as special purpose http server.
.tp
.B \-i
Interactive, provide prompts.
.tp
.OPTreq \-L dir
Specify the directory under which one or more logging repositories can
be stored.  
.tp
.OPTreq \-l log
Log accesses in 
.ARG log ;
if
.ARG log
is not specified, then log to stderr.
.tp
.OPTreq \-P pfile
Write the pid of daemon process into this file at startup.
.tp
.OPTreq \-p port
Specify an alternative port.  The default port is currently
0x3962 (aka 14690) but that will change once we get a
reserved port. 
.tp
.OPTreq \-t num
Exit after 
.ARG num
seconds. (used when debugging)
.tp
.OPTreq \-u uid
Run as UID
.ARG uid .
.tp
.OPTreq \-x cmd
Exclude 
.ARG cmd
from the allowed command list.
.SH EXAMPLES
.LP
We use the following in 
.B /var/bitkeeper/repositories
to provide anonymous read only access to some \*(BK repositories.  
.DS
#----------------------\ cut\ here\ --------------------------
/home/bk/LMbench \-p5000 \-xcd \-xpush \-u99
/home/bk/bitcluster \-p6000 \-xcd \-xpush \-u99
/home/bk/one \-p7000 \-xcd \-xpush \-u99
#----------------------\ cut\ here\ --------------------------
.DE
.LP
The init script shown below can be generated with a 
.DS
$ bk getmsg bitkeeper.init
.DE
We use the it in
.BR /etc/rc.d/init.d/bitkeeper
to start up \*(BK on bitkeeper.com (a Red Hat based Linux system):
.DS
#----------------------\ cut\ here\ --------------------------
#!/bin/sh
#
# bitkeeper	Start/stop the bitkeeper daemon.
# 		@(#)bitkeeper.init 1.1 Copyright (c) 2000 <NAME>

# 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"
		;;
    start)	cd $VAR || exit 1
		test \-f repositories || {
			echo Nothing advertised
			exit 0
		}
		while read dir opts
		do	(
			cd $dir || exit 1
			F=`basename $dir`
			bk bkd $opts \-l$VAR/log.$F \-P$VAR/pid.$F
			echo Started bkd $opts in $dir
			)
		done < repositories
		;;

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

    status)	ps \-axf | grep bkd
		;;

    *)		echo "Usage: bitkeeper {start|stop}"
		exit 1
		;;
esac
exit 0
#----------------------\ cut\ here\ --------------------------
.DE
.SH BUGS
Needs 
.B ssh
to provide access controlled, authenticated users.
One could argue that this is code reuse rather than a bug.
.LP
\*(BM
does not ship
.B ssh
since it is export controlled.
.SH "SEE ALSO"
.SA parent
.SA Howto-bkd 1
.\" help://anonymous
.\" help://deamon
.\" help://daemon
.\" help://demon
.\" help://security
.SH CATEGORY
.B Repository
.br
.B Admin

{'fraction_non_alphanumeric': 0.1310473725828481, 'fraction_numerical': 0.011357918194234777, 'mean_word_length': 2.5291730086250634, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6391303', 'n_tokens_mistral': 5303, 'n_tokens_neox': 4866, 'n_words': 2247}