.\"
.\" Copyright (c) 2007
.\"     The DragonFly Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific, prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $DragonFly: src/sbin/syslink/syslink.8,v 1.1 2007/04/16 17:36:04 dillon Exp $
.\"
.Dd April 14, 2007
.Dt SYSLINK 8
.Os
.Sh NAME
.Nm syslink
.Nd manage system resource links
.Sh SYNOPSIS
.Nm
.Op Fl lnv
.Op Ar sysid[:linkid]
.Nm
.Op Fl fnv
.Op Fl p Ar pidfile
.Ar sysid
.Cm add
.Ar [protocol:]target[/bits]
.Op Cm label Ar name
.Op Cm port Ar port
.Nm
.Op Fl fnv
.Ar sysid[:linkid]
.Cm delete
.Nm
.Op Fl fnv
.Ar sysid[:linkid]
.Cm modify
.Op Cm label Ar name
.Sh DESCRIPTION
The
.Nm
utility manages the system syslink infrastructure.
It may be used to list, add, modify, or delete elements of the syslink
mesh managed by the current host.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl f
Disable prompting, force the operation.
.It Fl n
List network addresses numerically, else a reverse DNS lookup will be made
.It Fl v
Generate more verbose output.  The more
.Fl v
options specified, the more verbose the output.
.It Fl l
Dump the entire list of route nodes and links, dump a specific route
node, or dump a specific link.
.It Fl p Ar pidfile
This option must be specified when adding targets that require
.Nm
to fork and run in the background.
.It Cm add Ar [protocol:]target[/bits] Ar options...
Associate a new link with the specified router.  Stream or packet switched
links may be specified.  If the link represents a subnet the number of bits
for the subnet must be specified and must support broadcast addressing.
In addition to being able to operate over a standard UDP broadcast network
it is possible to implement a subnet over a point to point link such as
a TCP connection, pipe, or point-to-point UDP connection.  In these cases
the target is responsible for handling the broadcast address in the syslink
messages.  If no protocol is specified, a stream TCP connection is assumed
if no subnet is specified and a broadcastable UDP subnet is assumed if a
subnet is specified.
.It Cm del[ete] Ar options...
Delete an existing link or router.  A router may only be deleted if no
links are associated with it.
.It Cm mod[ify] Ar options...
Modify an existing link or router.  Currently only the label may be modified.
.El
.Pp
A sysid or linkid may be specified in hex using a
.Cm 0x
prefix, or symbolically using its label name.
.Pp
.Nm
uses port 32 by default for tcp and udp protocols.  The port may be
overridden using the
.Cm port
specification.
.Sh PROTOCOLS
The following protocol specifications are supported
.Bl -tag -width indent
.It Cm tcp: Ns Ar host Ns Op /bits
.Nm
will connect to the target host, which may be specified as an IP address or
domain name, and associate the resulting descriptor with the syslink
route node.
Note that you may specify a subnet, in which case the target of the
point-to-point link will be responsible for handling subnet addresses
in the syslink messages.
.It Cm udp: Ns Ar host Ns Op /bits
.Nm
will connect to the target host or broadcast address, which may be specified
as an IP address or domain name, and associate the resulting descriptor
with the syslink route node.
The kernel will use the
.Xr sendto 2
facility to distribute syslink messages to individual or broadcast targets
.It Cm udp_ptp: Ns Ar host Ns Op /bits
.Nm
will construct a non-broadcast point-to-point UDP connection and
associate it with the syslink route node.
Note that you may specify a subnet, in which case the target of the
point-to-point link will be responsible for handling subnet addresses
in the syslink messages.
.It Cm pipe: Ns Ar descriptor Ns Op /bits
.Nm
will associate the specified descriptor number with the syslink
route node.  The descriptor should represent a full duplex stream connection.
.It Cm fifo: Ns Ar path Ns Op /bits
.Nm
will open the specified file, which should be a fifo or otherwise
represent a full duplex stream connection, and associate it with the
syslink route node.
.It Cm listen: Ns Ar bindaddr Ns Cm /bits
.Nm
will bind to the specified address (use 'any' for a wildcard binding),
fork, and run in the background accepting connections.
A pipe will be associated with the syslink route node and the
background process will route data from the accepted connections to
the route node and vise-versa.
A subnet specification is mandatory and determines the maximum number
of connections the background process will maintain (minus 2).  For
example, if 8 bits is specified, 254 connections can be maintained.
The pid of the background service will be written to the pidfile.
.El
.Sh FILES
.Sh EXAMPLES
.Pp
.Dl "syslink root add"
.Dl "syslink root add udp:10.0.0.255/8 label mylan"
.Dl "syslink -l root:mylan"
.Dl "syslink -l"
.Sh COMPATIBILITY
This is a
.Dx
specific command.
.Sh HISTORY
A
.Nm
utility first appeared in
.Dx 1.9 .