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