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