1.\" $Id: pppctl.8,v 1.10 1998/05/13 07:57:44 phk Exp $ 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. 188