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