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 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 don't 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 70Don't 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 EXAMPLES 114If you run 115.Nm ppp 116in 117.Fl auto 118mode, 119.Nm 120can be used to automate many frequent tasks (you can actually control 121.Nm ppp 122in any mode except interactive mode). 123Use of the 124.Fl p 125option is discouraged (even in scripts that aren't readable by others) 126as a 127.Xr ps 1 128listing may reveal your secret. 129.Pp 130The best way to allow easy, secure 131.Nm 132access is to create a local server socket in 133.Pa /etc/ppp/ppp.conf 134(in the correct section) like this: 135.Bd -literal -offset indent 136set server /var/run/internet "" 0177 137.Ed 138.Pp 139This will instruct 140.Nm ppp 141to create a local domain socket, with srw------- permissions and no 142password, allowing access only to the user that invoked 143.Nm ppp . 144Refer to the 145.Xr ppp 8 146man page for further details. 147.Pp 148You can now create some easy-access scripts. 149To connect to the internet: 150.Bd -literal -offset indent 151#! /bin/sh 152test $# -eq 0 && time=300 || time=$1 153exec pppctl /var/run/internet set timeout $time\\; dial 154.Ed 155.Pp 156To disconnect: 157.Bd -literal -offset indent 158#! /bin/sh 159exec pppctl /var/run/internet set timeout 300\\; close 160.Ed 161.Pp 162To check if the line is up: 163.Bd -literal -offset indent 164#! /bin/sh 165pppctl -p '' -v /var/run/internet quit | grep ^PPP >/dev/null 166if [ $? -eq 0 ]; then 167 echo Link is up 168else 169 echo Link is down 170fi 171.Ed 172.Pp 173You can even make a generic script: 174.Bd -literal -offset indent 175#! /bin/sh 176exec pppctl /var/run/internet "$@" 177.Ed 178.Pp 179You could also use 180.Nm 181to control when dial-on-demand works. 182Suppose you want 183.Nm ppp 184to run all the time, but you want to prevent dial-out between 8pm and 8am 185each day. 186However, any connections active at 8pm should continue to remain 187active until they are closed or naturally time out. 188.Pp 189A 190.Xr cron 8 191entry for 8pm which runs 192.Bd -literal -offset indent 193pppctl /var/run/internet set filter dial 0 deny 0 0 194.Ed 195.Pp 196will block all further dial requests, and the corresponding 8am entry 197.Bd -literal -offset indent 198pppctl /var/run/internet set filter dial -1 199.Ed 200.Pp 201will allow them again. 202.Sh ENVIRONMENT 203The following environment variables are understood by 204.Nm 205when in interactive mode: 206.Bl -tag -width XXXXXXXXXX 207.It Dv EL_SIZE 208The number of history lines. 209The default is 20. 210.It Dv EL_EDITOR 211The edit mode. 212Only values of "emacs" and "vi" are accepted. 213Other values 214are silently ignored. 215This environment variable will override the 216.Ar bind -v 217and 218.Ar bind -e 219commands in 220.Pa ~/.editrc . 221.El 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