1.\" $FreeBSD$ 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 22This program provides command line control of the 23.Xr ppp 8 24daemon. Its primary use is to facilitate simple scripts that 25control a running daemon. 26.Pp 27.Nm Pppctl 28is passed at least one argument, specifying the socket on which 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 211command first appeared in 212.Fx 2.2.5 . 213