1.\" $FreeBSD: src/usr.sbin/pppctl/pppctl.8,v 1.12.2.8 2003/03/11 22:31:30 trhodes Exp $ 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. Its 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. Refer to the 32.Sq set server 33command of 34.Nm ppp 35for details. If the socket contains a leading '/', it 36is taken as an 37.Dv AF_LOCAL 38socket. If it contains a colon, it is treated as a 39.Ar host : Ns Ar port 40pair, otherwise it is treated as a TCP port specification on the 41local machine (127.0.0.1). Both the 42.Ar host 43and 44.Ar port 45may be specified numerically if you wish to avoid a DNS lookup 46or don't have an entry for the given port in 47.Pa /etc/services . 48.Pp 49All remaining arguments are concatenated to form the 50.Ar command Ns (s) 51that will be sent to the 52.Nm ppp 53daemon. If any semi-colon characters are found, they are treated as 54.Ar command 55delimiters, allowing more than one 56.Ar command 57in a given 58.Sq session . 59For example: 60.Bd -literal -offset indent 61pppctl 3000 set timeout 300\\; show timeout 62.Ed 63.Pp 64Don't forget to escape or quote the ';' as it is a special character 65for most shells. 66.Pp 67If no 68.Ar command 69arguments are given, 70.Nm 71enters interactive mode, where commands are read from standard input. 72When reading commands, the 73.Xr editline 3 74library is used, allowing command-line editing (with 75.Xr editrc 5 76defining editing behaviour). The history size 77defaults to 78.Em 20 lines . 79.Pp 80The following command line options are available: 81.Bl -tag -width Ds 82.It Fl v 83Display all data sent to and received from the 84.Nm ppp 85daemon. Normally, 86.Nm 87displays only non-prompt lines received. This option is ignored in 88interactive mode. 89.It Fl t Ar n 90Use a timeout of 91.Ar n 92instead of the default 2 seconds when connecting. This may be required 93if you wish to control a daemon over a slow (or even a dialup) link. 94.It Fl p Ar passwd 95Specify the password required by the 96.Nm ppp 97daemon. If this switch is not used, 98.Nm 99will prompt for a password once it has successfully connected to 100.Nm ppp . 101.El 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.Sh SEE ALSO 204.Xr ps 1 , 205.Xr editline 3 , 206.Xr editrc 5 , 207.Xr services 5 , 208.Xr ppp 8 209.Sh HISTORY 210The 211.Nm 212utility first appeared in 213.Fx 2.2.5 . 214