sbin/syslink/syslink.8

   1 .\"
   2 .\" Copyright (c) 2007
   3 .\"     The DragonFly Project.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\" 3. Neither the name of The DragonFly Project nor the names of its
  16 .\"    contributors may be used to endorse or promote products derived
  17 .\"    from this software without specific, prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $DragonFly: src/sbin/syslink/syslink.8,v 1.1 2007/04/16 17:36:04 dillon Exp $
  33 .\"
  34 .Dd April 14, 2007
  35 .Dt SYSLINK 8
  36 .Os
  37 .Sh NAME
  38 .Nm syslink
  39 .Nd manage system resource links
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl lnv
  43 .Op Ar sysid[:linkid]
  44 .Nm
  45 .Op Fl fnv
  46 .Op Fl p Ar pidfile
  47 .Ar sysid
  48 .Cm add
  49 .Ar [protocol:]target[/bits]
  50 .Op Cm label Ar name
  51 .Op Cm port Ar port
  52 .Nm
  53 .Op Fl fnv
  54 .Ar sysid[:linkid]
  55 .Cm delete
  56 .Nm
  57 .Op Fl fnv
  58 .Ar sysid[:linkid]
  59 .Cm modify
  60 .Op Cm label Ar name
  61 .Sh DESCRIPTION
  62 The
  63 .Nm
  64 utility manages the system syslink infrastructure.
  65 It may be used to list, add, modify, or delete elements of the syslink
  66 mesh managed by the current host.
  67 .Pp
  68 The following options are available:
  69 .Bl -tag -width indent
  70 .It Fl f
  71 Disable prompting, force the operation.
  72 .It Fl n
  73 List network addresses numerically, else a reverse DNS lookup will be made
  74 .It Fl v
  75 Generate more verbose output.  The more
  76 .Fl v
  77 options specified, the more verbose the output.
  78 .It Fl l
  79 Dump the entire list of route nodes and links, dump a specific route
  80 node, or dump a specific link.
  81 .It Fl p Ar pidfile
  82 This option must be specified when adding targets that require
  83 .Nm
  84 to fork and run in the background.
  85 .It Cm add Ar [protocol:]target[/bits] Ar options...
  86 Associate a new link with the specified router.  Stream or packet switched
  87 links may be specified.  If the link represents a subnet the number of bits
  88 for the subnet must be specified and must support broadcast addressing.
  89 In addition to being able to operate over a standard UDP broadcast network
  90 it is possible to implement a subnet over a point to point link such as
  91 a TCP connection, pipe, or point-to-point UDP connection.  In these cases
  92 the target is responsible for handling the broadcast address in the syslink
  93 messages.  If no protocol is specified, a stream TCP connection is assumed
  94 if no subnet is specified and a broadcastable UDP subnet is assumed if a
  95 subnet is specified.
  96 .It Cm del[ete] Ar options...
  97 Delete an existing link or router.  A router may only be deleted if no
  98 links are associated with it.
  99 .It Cm mod[ify] Ar options...
 100 Modify an existing link or router.  Currently only the label may be modified.
 101 .El
 102 .Pp
 103 A sysid or linkid may be specified in hex using a
 104 .Cm 0x
 105 prefix, or symbolically using its label name.
 106 .Pp
 107 .Nm
 108 uses port 32 by default for tcp and udp protocols.  The port may be
 109 overridden using the
 110 .Cm port
 111 specification.
 112 .Sh PROTOCOLS
 113 The following protocol specifications are supported
 114 .Bl -tag -width indent
 115 .It Cm tcp: Ns Ar host Ns Op /bits
 116 .Nm
 117 will connect to the target host, which may be specified as an IP address or
 118 domain name, and associate the resulting descriptor with the syslink
 119 route node.
 120 Note that you may specify a subnet, in which case the target of the
 121 point-to-point link will be responsible for handling subnet addresses
 122 in the syslink messages.
 123 .It Cm udp: Ns Ar host Ns Op /bits
 124 .Nm
 125 will connect to the target host or broadcast address, which may be specified
 126 as an IP address or domain name, and associate the resulting descriptor
 127 with the syslink route node.
 128 The kernel will use the
 129 .Xr sendto 2
 130 facility to distribute syslink messages to individual or broadcast targets
 131 .It Cm udp_ptp: Ns Ar host Ns Op /bits
 132 .Nm
 133 will construct a non-broadcast point-to-point UDP connection and
 134 associate it with the syslink route node.
 135 Note that you may specify a subnet, in which case the target of the
 136 point-to-point link will be responsible for handling subnet addresses
 137 in the syslink messages.
 138 .It Cm pipe: Ns Ar descriptor Ns Op /bits
 139 .Nm
 140 will associate the specified descriptor number with the syslink
 141 route node.  The descriptor should represent a full duplex stream connection.
 142 .It Cm fifo: Ns Ar path Ns Op /bits
 143 .Nm
 144 will open the specified file, which should be a fifo or otherwise
 145 represent a full duplex stream connection, and associate it with the
 146 syslink route node.
 147 .It Cm listen: Ns Ar bindaddr Ns Cm /bits
 148 .Nm
 149 will bind to the specified address (use 'any' for a wildcard binding),
 150 fork, and run in the background accepting connections.
 151 A pipe will be associated with the syslink route node and the
 152 background process will route data from the accepted connections to
 153 the route node and vise-versa.
 154 A subnet specification is mandatory and determines the maximum number
 155 of connections the background process will maintain (minus 2).  For
 156 example, if 8 bits is specified, 254 connections can be maintained.
 157 The pid of the background service will be written to the pidfile.
 158 .El
 159 .Sh FILES
 160 .Sh EXAMPLES
 161 .Pp
 162 .Dl "syslink root add"
 163 .Dl "syslink root add udp:10.0.0.255/8 label mylan"
 164 .Dl "syslink -l root:mylan"
 165 .Dl "syslink -l"
 166 .Sh COMPATIBILITY
 167 This is a
 168 .Dx
 169 specific command.
 170 .Sh HISTORY
 171 A
 172 .Nm
 173 utility first appeared in
 174 .Dx 1.9 .