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