.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BRSSCLA 1"
.TH BRSSCLA 1 "2016-07-07" "perl v5.24.1" "BP executables"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
brsscla \- BRSS\-based BP convergence layer adapter (input and output) task
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBbrsscla\fR \fIlocal_hostname\fR[:\fIlocal_port_nbr\fR][ \fIfirst_duct_nbr_in_scope\fR[ \fIlast_duct_nbr_in_scope\fR]]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1BRSS\s0 is the \*(L"server\*(R" side of the Bundle Relay Service (\s-1BRS\s0) convergence
layer protocol for \s-1BP. \s0 It is complemented by \s-1BRSC,\s0 the \*(L"client\*(R" side of
the \s-1BRS\s0 convergence layer protocol for \s-1BP.\s0
.PP
\&\fBbrsscla\fR is a background \*(L"daemon\*(R" task that spawns two plus N threads:
one that handles \s-1BRSS\s0 client connections and spawns sockets for continued data
interchange with connected clients; one that handles \s-1BRSS\s0 protocol output
by transmitting over those spawned sockets to the associated clients; and
one input thread for each spawned socket, to handle \s-1BRSS\s0 protocol input from 
the associated connected client.
.PP
The connection thread simply accepts connections on a \s-1TCP\s0 socket bound to
\&\fIlocal_hostname\fR and \fIlocal_port_nbr\fR and spawns reception threads.  The
default value for \fIlocal_port_nbr\fR, if omitted, is 80.
.PP
Each reception thread receives over the socket connection the node number
of the connecting client (in \s-1SDNV\s0 representation), followed by a 32\-bit time
tag and a 160\-bit \s-1HMAC\-SHA1\s0 digest of that time tag.  The node number must
be in the range \fIfirst_duct_nbr_in_scope\fR through \fIlast_duct_nbr_in_scope\fR
inclusive; when omitted, \fIfirst_duct_nbr_in_scope\fR defaults to 1 and
\&\fIlast_duct_nbr_in_scope\fR defaults to \fIfirst_duct_nbr_in_scope\fR plus 255.
The receiving thread also checks the time tag, requiring that it differ from
the current time by no more than \s-1BRSTERM \s0(default value 5) seconds.  It then
recomputes the digest
value using the \s-1HMAC\-SHA1\s0 key named "\fInode_number\fR.brs" as recorded in the
\&\s-1ION\s0 security database (see \fIionsecrc\fR\|(5)), requiring that the supplied and
computed digests be identical.  If all registration conditions are met, the
receiving thread sends the client a countersign \*(-- a similarly computed
\&\s-1HMAC\-SHA1\s0 digest, for the time tag that is 1 second later than the provided
time tag \*(-- to assure the client of its own authenticity, then commences
receiving bundles over the connected socket.  Each bundle received on the
connection is preceded by its length, a 32\-bit unsigned integer in network
byte order.  The received bundles are passed to the bundle protocol agent
on the local \s-1ION\s0 node.
.PP
The output thread extracts bundles from the queues of bundles ready for
transmission via \s-1BRSS\s0 to remote bundle protocol agents, finds the connected
clients whose node numbers match the proximate receiver node numbers assigned
to the bundles by the routing daemons that enqueued them, and transmits the
bundles over the sockets to those clients.  Each transmitted bundle is
preceded by its length, a 32\-bit unsigned integer in network byte order.
.PP
Note that \fBbrsscla\fR is a \*(L"promiscuous\*(R" convergence layer daemon, able to
transmit bundles to any \s-1BRSS\s0 destination induct for which it has received
a connection.  Its sole outduct's name is the name of the corresponding induct,
rather than the induct name of any single \s-1BRSS\s0 destination induct to which the
outduct might be dedicated, so scheme configuration directives that cite this
outduct must provide destination induct IDs.  For the \s-1BRS\s0 convergence-layer
protocol, destination induct IDs are simply the node numbers of connected
clients.
.PP
\&\fBbrsscla\fR is spawned automatically by \fBbpadmin\fR in response to the 's' (\s-1START\s0)
command that starts operation of the Bundle Protocol, and it is terminated by
\&\fBbpadmin\fR in response to an 'x' (\s-1STOP\s0) command.  \fBbrsscla\fR can also be
spawned and terminated in response to \s-1START\s0 and \s-1STOP\s0 commands that pertain
specifically to the \s-1BRSS\s0 convergence layer protocol.
.SH "EXIT STATUS"
.IX Header "EXIT STATUS"
.ie n .IP """0""" 4
.el .IP "``0''" 4
.IX Item "0"
\&\fBbrsscla\fR terminated normally, for reasons noted in the \fBion.log\fR file.  If
this termination was not commanded, investigate and solve the problem identified
in the log file and use \fBbpadmin\fR to restart the \s-1BRSS\s0 protocol.
.ie n .IP """1""" 4
.el .IP "``1''" 4
.IX Item "1"
\&\fBbrsscla\fR terminated abnormally, for reasons noted in the \fBion.log\fR file.
Investigate and solve the problem identified in the log file, then use
\&\fBbpadmin\fR to restart the \s-1BRSS\s0 protocol.
.SH "FILES"
.IX Header "FILES"
No configuration files are needed.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
No environment variables apply.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
The following diagnostics may be issued to the \fBion.log\fR log file:
.IP "brsscla can't attach to \s-1BP.\s0" 4
.IX Item "brsscla can't attach to BP."
\&\fBbpadmin\fR has not yet initialized Bundle Protocol operations.
.IP "No such brss induct." 4
.IX Item "No such brss induct."
No \s-1BRSS\s0 induct with duct name matching \fIlocal_hostname\fR and \fIlocal_port_nbr\fR
has been added to the \s-1BP\s0 database.  Use \fBbpadmin\fR to stop the \s-1BRSS\s0
convergence-layer protocol, add the induct, and then restart the \s-1BRSS\s0 protocol.
.IP "\s-1CLI\s0 task is already started for this duct." 4
.IX Item "CLI task is already started for this duct."
Redundant initiation of \fBbrsscla\fR.
.IP "No such brss outduct." 4
.IX Item "No such brss outduct."
No \s-1BRSS\s0 outduct with duct name matching \fIlocal_hostname\fR and \fIlocal_port_nbr\fR
has been added to the \s-1BP\s0 database.  Use \fBbpadmin\fR to stop the \s-1BRSS\s0
convergence-layer protocol, add the outduct, and then restart the \s-1BRSS\s0 protocol.
.IP "Can't get \s-1IP\s0 address for host" 4
.IX Item "Can't get IP address for host"
Operating system error.  Check errtext, correct problem, and restart \s-1BRSS.\s0
.IP "Can't open \s-1TCP\s0 socket" 4
.IX Item "Can't open TCP socket"
Operating system error \*(-- unable to open \s-1TCP\s0 socket for accepting connections.
Check errtext, correct problem, and restart \s-1BRSS.\s0
.IP "Can't initialize socket (note: must be root for port 80)" 4
.IX Item "Can't initialize socket (note: must be root for port 80)"
Operating system error.  Check errtext, correct problem, and restart \s-1BRSS.\s0
.IP "brsscla can't create sender thread" 4
.IX Item "brsscla can't create sender thread"
Operating system error.  Check errtext, correct problem, and restart \s-1BRSS.\s0
.IP "brsscla can't create access thread" 4
.IX Item "brsscla can't create access thread"
Operating system error.  Check errtext, correct problem, and restart \s-1BRSS.\s0
.SH "BUGS"
.IX Header "BUGS"
Report bugs to <ion\-bugs@korgano.eecs.ohiou.edu>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbpadmin\fR\|(1), \fIbprc\fR\|(5), \fIbrsccla\fR\|(1)