894b5aa1e9ffe27a1dc128453dd4ef8c215507cf
[dragonfly.git] / usr.sbin / sliplogin / sliplogin.8
1 .\" Copyright (c) 1990, 1991, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\"    must display the following acknowledgement:
14 .\"     This product includes software developed by the University of
15 .\"     California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\"    may be used to endorse or promote products derived from this software
18 .\"    without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\"     @(#)sliplogin.8 8.2 (Berkeley) 1/5/94
33 .\" $FreeBSD: src/usr.sbin/sliplogin/sliplogin.8,v 1.12.2.5 2003/03/11 22:31:33 trhodes Exp $
34 .\" $DragonFly: src/usr.sbin/sliplogin/sliplogin.8,v 1.2 2003/06/17 04:30:03 dillon Exp $
35 .\"
36 .Dd January 5, 1994
37 .Dt SLIPLOGIN 8
38 .Os
39 .Sh NAME
40 .Nm sliplogin
41 .Nd attach a serial line network interface
42 .Sh SYNOPSIS
43 .Nm
44 .Op Ar loginname Op Ar device
45 .Sh DESCRIPTION
46 The
47 .Nm
48 utility is used to turn the terminal line on standard input (or
49 .Ar device )
50 into a Serial Line IP
51 .Pq Tn SLIP
52 link to a remote host.  To do this, the program
53 searches the file
54 .Pa /etc/sliphome/slip.hosts
55 for an entry matching
56 .Ar loginname
57 (which defaults to the current login name if omitted).
58 If a matching entry is found, the line is configured appropriately
59 for slip (8-bit transparent i/o) and converted to
60 .Tn SLIP
61 line discipline using the optional line discipline parameters.
62 .Pp
63 The optional line discipline parameters consist of one or more of
64 the following;
65 .Sq normal ,
66 .Sq compress ,
67 .Sq noicmp ,
68 or
69 .Sq autocomp
70 which correspond respectively to
71 .Sq use normal line discipline
72 (no header compression),
73 .Sq enable VJ header compression ,
74 .Sq throw away ICMP packets ,
75 and
76 .Sq auto enable VJ header compression
77 (only if the remote end of the link also supports it).
78 .Pp
79 Then a shell script is invoked to initialize the slip
80 interface with the appropriate local and remote
81 .Tn IP
82 address,
83 netmask, etc.
84 .Pp
85 The usual initialization script is
86 .Pa /etc/sliphome/slip.login
87 but, if particular hosts need special initialization, the file
88 .Pa /etc/sliphome/slip.login. Ns Ar loginname
89 will be executed instead if it exists.
90 The script is invoked with the parameters
91 .Bl -tag -width slipunit
92 .It Em slipunit
93 The unit number of the slip interface assigned to this line.  E.g.,
94 .Sy 0
95 for
96 .Sy sl0 .
97 .It Em speed
98 The speed of the line.
99 .It Em args
100 The arguments from the
101 .Pa /etc/sliphome/slip.hosts
102 entry, in order starting with
103 .Ar loginname .
104 .El
105 .Pp
106 Only the super-user may attach a network interface.  The interface is
107 automatically detached when the other end hangs up or the
108 .Nm
109 process dies.  If the kernel slip
110 module has been configured for it, all routes through that interface will
111 also disappear at the same time.  If there is other processing a site
112 would like done on hangup, the file
113 .Pa /etc/sliphome/slip.logout
114 or
115 .Pa /etc/sliphome/slip.logout. Ns Ar loginname
116 is executed if it exists.  It is given the same arguments as the login script.
117 .Ss Format of /etc/sliphome/slip.hosts
118 Comments (lines starting with a `#') and blank lines (or started
119 with space) are ignored.
120 Other lines must start with a
121 .Ar loginname
122 but the remaining arguments can be whatever is appropriate for the
123 .Pa  slip.login
124 file that will be executed for that name.
125 Arguments are separated by white space and follow normal
126 .Xr sh 1
127 quoting conventions (however,
128 .Ar loginname
129 cannot be quoted).
130 Usually, lines have the form
131 .Bd -literal -offset indent
132 loginname local-address remote-address netmask opt-args
133 .Ed
134 .Pp
135 where
136 .Em local-address
137 and
138 .Em remote-address
139 are the IP host names or addresses of the local and remote ends of the
140 slip line and
141 .Em netmask
142 is the appropriate IP netmask.  These arguments are passed
143 directly to
144 .Xr ifconfig 8 .
145 .Em Opt-args
146 are optional arguments used to configure the line.
147 .Sh FreeBSD Additions
148 An additional SLIP configuration file (if present) is
149 .Pa /etc/sliphome/slip.slparms .
150 If particular hosts need different configurations, the file
151 .Pa /etc/sliphome/slip.slparms. Ns Ar loginname
152 will be parsed instead if it exists.
153 .Ss Format of /etc/sliphome/slip.slparms*
154 Comments (lines starting with a `#') and blank lines (or started with
155 space) are ignored.
156 This file contains from one to three numeric parameters separated with spaces,
157 in order:
158 .Ar keepalive ,
159 .Ar outfill
160 and
161 .Ar slunit .
162 .Bl -tag -width keepalive
163 .It Ar keepalive
164 Set SLIP "keep alive" timeout in seconds.
165 If FRAME_END is not received in
166 this amount of time,
167 .Nm
168 closes the line and exits.
169 The default value is no timeout (zero).
170 .It Ar outfill
171 Set SLIP "out fill" timeout in seconds.
172 It forces at least one FRAME_END
173 to be sent during this time period, which is necessary for the "keep alive"
174 timeout on the remote side.
175 The default value is no timeout (zero).
176 .It Ar slunit
177 Set the SLIP unit number directly.
178 Use with caution, because no check is made
179 for two interfaces with same number.
180 By default sliplogin dynamically assigns the unit number.
181 .El
182 .Pp
183 If latter two parameters are omitted, they will not affect the
184 corresponding SLIP configuration.
185 If any of first two parameters is equal to zero, it will not affect
186 the corresponding SLIP configuration.
187 .Sh EXAMPLES
188 The normal use of
189 .Nm
190 is to create a
191 .Pa /etc/passwd
192 entry for each legal, remote slip site with
193 .Nm
194 as the shell for that entry.  E.g.,
195 .Bd -literal
196 Sfoo:ikhuy6:2010:1:slip line to foo:/tmp:/usr/sbin/sliplogin
197 .Ed
198 .Pp
199 (Our convention is to name the account used by remote host
200 .Ar hostname
201 as
202 .Em Shostname . )
203 Then an entry is added to
204 .Pa slip.hosts
205 that looks like:
206 .Pp
207 .Bd -literal -offset indent -compact
208 Sfoo    `hostname`      foo     netmask
209 .Ed
210 .Pp
211 where
212 .Em `hostname`
213 will be evaluated by
214 .Xr sh
215 to the local host name and
216 .Em netmask
217 is the local host IP netmask.
218 .Pp
219 Note that
220 .Nm
221 must be setuid to root and, while not a security hole, moral defectives
222 can use it to place terminal lines in an unusable state and/or deny
223 access to legitimate users of a remote slip line.  To prevent this,
224 .Nm
225 is installed as user
226 .Em root ,
227 group
228 .Em network
229 and mode 4550 so that only members of group
230 .Em network
231 may run
232 .Nm .
233 The system administrator should make sure that all legitimate users
234 are a member of the correct group.
235 .Sh DIAGNOSTICS
236 The
237 .Nm
238 utility logs various information to the system log daemon,
239 .Xr syslogd 8 ,
240 with a facility code of
241 .Em daemon .
242 The messages are listed here, grouped by severity level.
243 .Pp
244 .Sy Error Severity
245 .Bl -tag -width Ds -compact
246 .It Sy ioctl (TCGETS): Em reason
247 A
248 .Dv TCGETS
249 .Fn ioctl
250 to get the line parameters failed.
251 .Pp
252 .It Sy ioctl (TCSETS): Em reason
253 A
254 .Dv TCSETS
255 .Fn ioctl
256 to set the line parameters failed.
257 .Pp
258 .It Sy /etc/sliphome/slip.hosts: Em reason
259 The
260 .Pa /etc/sliphome/slip.hosts
261 file could not be opened.
262 .Pp
263 .It Sy access denied for Em user
264 No entry for
265 .Em user
266 was found in
267 .Pa /etc/sliphome/slip.hosts .
268 .El
269 .Pp
270 .Sy Notice Severity
271 .Bl -tag -width Ds -compact
272 .It Sy "attaching slip unit" Em unit Sy for Ar loginname
273 .Tn SLIP
274 unit
275 .Em unit
276 was successfully attached.
277 .El
278 .Sh FILES
279 .Bl -tag -width indent
280 .It Pa /etc/sliphome/slip.hosts
281 list of host login names and parameters.
282 .It Pa /etc/sliphome/slip.login
283 script executed when a connection is made.
284 .It Pa /etc/sliphome/slip.login. Ns Ar loginname
285 script executed when a connection is made by
286 .Ar loginname .
287 .It Pa /etc/sliphome/slip.logout
288 script executed when a connection is lost.
289 .It Pa /etc/sliphome/slip.logout. Ns Ar loginname
290 script executed when a connection is lost by
291 .Ar loginname .
292 .It Pa /etc/sliphome/slip.slparms
293 extra parameters file.
294 .It Pa /etc/sliphome/slip.slparms. Ns Ar loginname
295 extra parameters file for
296 .Ar loginname .
297 .It Pa /var/run/ Ns Ar ttyXn Ns Pa .if
298 contains the name of the network interface used by the sliplogin process on
299 .Ar ttyXn .
300 .It Pa /var/run/ Ns Ar slX Ns Pa .pid
301 contains the PID of the sliplogin process which is using interface
302 .Ar slX .
303 .El
304 .Sh SEE ALSO
305 .Xr slattach 8 ,
306 .Xr syslogd 8
307 .Pp
308 .Pa /usr/share/examples/sliplogin
309 .Sh HISTORY
310 The
311 .Nm
312 utility appeared in
313 .Bx 4.3 Reno .