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