26d8cee660a63637ff7a31bd7c4e5fc4ee4c8ee0
[dragonfly.git] / usr.sbin / pppctl / pppctl.8
1 .\" $FreeBSD: src/usr.sbin/pppctl/pppctl.8,v 1.12.2.8 2003/03/11 22:31:30 trhodes Exp $
2 .\" $DragonFly: src/usr.sbin/pppctl/pppctl.8,v 1.2 2003/06/17 04:30:01 dillon Exp $
3 .Dd June 26, 1997
4 .Os
5 .Dt PPPCTL 8
6 .Sh NAME
7 .Nm pppctl
8 .Nd PPP control program
9 .Sh SYNOPSIS
10 .Nm
11 .Op Fl v
12 .Op Fl t Ar n
13 .Op Fl p Ar passwd
14 .Xo Oo Ar host : Oc Ns
15 .Ar Port | LocalSocket
16 .Xc
17 .Oo
18 .Sm off
19 .Ar command Oo ; Ar command Oc Ar ...
20 .Sm on
21 .Oc
22 .Sh DESCRIPTION
23 This utility provides command line control of the
24 .Xr ppp 8
25 daemon.  Its primary use is to facilitate simple scripts that
26 control a running daemon.
27 .Pp
28 The
29 .Nm
30 utility is passed at least one argument, specifying the socket on which
31 .Nm ppp
32 is listening.  Refer to the
33 .Sq set server
34 command of
35 .Nm ppp
36 for details.  If the socket contains a leading '/', it
37 is taken as an
38 .Dv AF_LOCAL
39 socket.  If it contains a colon, it is treated as a
40 .Ar host : Ns Ar port
41 pair, otherwise it is treated as a TCP port specification on the
42 local machine (127.0.0.1).  Both the
43 .Ar host
44 and
45 .Ar port
46 may be specified numerically if you wish to avoid a DNS lookup
47 or don't have an entry for the given port in
48 .Pa /etc/services .
49 .Pp
50 All remaining arguments are concatenated to form the
51 .Ar command Ns (s)
52 that will be sent to the
53 .Nm ppp
54 daemon.  If any semi-colon characters are found, they are treated as
55 .Ar command
56 delimiters, allowing more than one
57 .Ar command
58 in a given
59 .Sq session .
60 For example:
61 .Bd -literal -offset indent
62 pppctl 3000 set timeout 300\\; show timeout
63 .Ed
64 .Pp
65 Don't forget to escape or quote the ';' as it is a special character
66 for most shells.
67 .Pp
68 If no
69 .Ar command
70 arguments are given,
71 .Nm
72 enters interactive mode, where commands are read from standard input.
73 When reading commands, the
74 .Xr editline 3
75 library is used, allowing command-line editing (with
76 .Xr editrc 5
77 defining editing behaviour).  The history size
78 defaults to
79 .Em 20 lines .
80 .Pp
81 The following command line options are available:
82 .Bl -tag -width Ds
83 .It Fl v
84 Display all data sent to and received from the
85 .Nm ppp
86 daemon.  Normally,
87 .Nm
88 displays only non-prompt lines received.  This option is ignored in
89 interactive mode.
90 .It Fl t Ar n
91 Use a timeout of
92 .Ar n
93 instead of the default 2 seconds when connecting.  This may be required
94 if you wish to control a daemon over a slow (or even a dialup) link.
95 .It Fl p Ar passwd
96 Specify the password required by the
97 .Nm ppp
98 daemon.  If this switch is not used,
99 .Nm
100 will prompt for a password once it has successfully connected to
101 .Nm ppp .
102 .El
103 .Sh EXAMPLES
104 If you run
105 .Nm ppp
106 in
107 .Fl auto
108 mode,
109 .Nm
110 can be used to automate many frequent tasks (you can actually control
111 .Nm ppp
112 in any mode except interactive mode).  Use of the
113 .Fl p
114 option is discouraged (even in scripts that aren't readable by others)
115 as a
116 .Xr ps 1
117 listing may reveal your secret.
118 .Pp
119 The best way to allow easy, secure
120 .Nm
121 access is to create a local server socket in
122 .Pa /etc/ppp/ppp.conf
123 (in the correct section) like this:
124 .Bd -literal -offset indent
125 set server /var/run/internet "" 0177
126 .Ed
127 .Pp
128 This will instruct
129 .Nm ppp
130 to create a local domain socket, with srw------- permissions and no
131 password, allowing access only to the user that invoked
132 .Nm ppp .
133 Refer to the
134 .Xr ppp 8
135 man page for further details.
136 .Pp
137 You can now create some easy-access scripts.  To connect to the internet:
138 .Bd -literal -offset indent
139 #! /bin/sh
140 test $# -eq 0 && time=300 || time=$1
141 exec pppctl /var/run/internet set timeout $time\\; dial
142 .Ed
143 .Pp
144 To disconnect:
145 .Bd -literal -offset indent
146 #! /bin/sh
147 exec pppctl /var/run/internet set timeout 300\\; close
148 .Ed
149 .Pp
150 To check if the line is up:
151 .Bd -literal -offset indent
152 #! /bin/sh
153 pppctl -p '' -v /var/run/internet quit | grep ^PPP >/dev/null
154 if [ $? -eq 0 ]; then
155   echo Link is up
156 else
157   echo Link is down
158 fi
159 .Ed
160 .Pp
161 You can even make a generic script:
162 .Bd -literal -offset indent
163 #! /bin/sh
164 exec pppctl /var/run/internet "$@"
165 .Ed
166 .Pp
167 You could also use
168 .Nm
169 to control when dial-on-demand works.  Suppose you want
170 .Nm ppp
171 to run all the time, but you want to prevent dial-out between 8pm and 8am
172 each day.  However, any connections active at 8pm should continue to remain
173 active until they are closed or naturally time out.
174 .Pp
175 A
176 .Xr cron 8
177 entry for 8pm which runs
178 .Bd -literal -offset indent
179 pppctl /var/run/internet set filter dial 0 deny 0 0
180 .Ed
181 .Pp
182 will block all further dial requests, and the corresponding 8am entry
183 .Bd -literal -offset indent
184 pppctl /var/run/internet set filter dial -1
185 .Ed
186 .Pp
187 will allow them again.
188 .Sh ENVIRONMENT
189 The following environment variables are understood by
190 .Nm
191 when in interactive mode:
192 .Bl -tag -width XXXXXXXXXX
193 .It Dv EL_SIZE
194 The number of history lines.  The default is 20.
195 .It Dv EL_EDITOR
196 The edit mode.  Only values of "emacs" and "vi" are accepted.  Other values
197 are silently ignored.  This environment variable will override the
198 .Ar bind -v
199 and
200 .Ar bind -e
201 commands in
202 .Pa ~/.editrc .
203 .El
204 .Sh SEE ALSO
205 .Xr ps 1 ,
206 .Xr editline 3 ,
207 .Xr editrc 5 ,
208 .Xr services 5 ,
209 .Xr ppp 8
210 .Sh HISTORY
211 The
212 .Nm
213 utility first appeared in
214 .Fx 2.2.5 .