1.\" $OpenBSD: bgplg.8,v 1.6 2010/04/03 21:40:51 sthen Exp $ 2.\" 3.\" Copyright (c) 2005, 2006 Reyk Floeter <reyk@vantronix.net> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: April 3 2010 $ 18.Dt BGPLG 8 19.Os 20.Sh NAME 21.Nm bgplg 22.Nd looking glass for the 23.Ox 24Border Gateway Protocol daemon 25.Sh SYNOPSIS 26.Nm bgplg 27.Sh DESCRIPTION 28The 29.Nm 30CGI program is a looking glass for the 31.Xr bgpd 8 32Border Gateway Protocol daemon. 33The looking glass will provide a simple web interface with read-only 34access to a restricted set of 35.Xr bgpd 8 36and system status information, which is typically used on route 37servers by Internet Service Providers (ISPs) and Internet eXchange 38points (IXs). 39It is intended to be used in a 40.Xr chroot 2 41environment in 42.Pa /var/www . 43.Pp 44.Nm 45is disabled by default. 46It requires four steps to enable the looking glass: 47.Bl -enum 48.It 49Update the file permission mode to allow the execution of the 50.Nm 51CGI program and the additional statically linked programs that have 52been installed into the 53.Xr chroot 2 54environment. 55.Pp 56For example, 57to allow execution of 58.Nm 59and the statically-linked version of 60.Xr bgpctl 8 : 61.Bd -literal -offset indent 62# chmod 0555 /var/www/cgi-bin/bgplg 63# chmod 0555 /var/www/bin/bgpctl 64.Ed 65.Pp 66External commands like 67.Xr ping 8 68and others will be hidden from the looking glass command 69list unless given the correct permissions. 70See the 71.Sx FILES 72section below for the list of installed programs. 73.It 74The programs 75.Xr ping 8 , 76.Xr ping6 8 , 77.Xr traceroute 8 78and 79.Xr traceroute6 8 80will require a copy of the resolver configuration file 81.Xr resolv.conf 5 82in the 83.Xr chroot 2 84environment for optional host name lookups. 85.Bd -literal -offset indent 86# mkdir /var/www/etc 87# cp /etc/resolv.conf /var/www/etc 88.Ed 89.It 90Start the Border Gateway Protocol daemon with a second, 91restricted, control socket that can be used 92from within the 93.Xr chroot 2 94environment. 95See 96.Xr bgpd 8 97for more information. 98.Pp 99For example, 100set the following in 101.Pa /etc/rc.conf.local 102to start 103.Xr bgpd 8 104using the second, restricted, control socket: 105.Pp 106.Dl bgpd_flags=\&"-r /var/www/logs/bgpd.rsock\&" 107.Pp 108.It 109Start the Apache Hypertext Transfer Protocol Server. 110See 111.Xr httpd 8 112for more information. 113.El 114.Sh FILES 115.Bl -tag -width "/var/www/conf/bgplg.headXX" -compact 116.It Pa /var/www/conf/bgplg.css 117Optional 118.Nm 119CSS style sheet. 120.It Pa /var/www/conf/bgplg.head 121Optional 122.Nm 123HTML header. 124.It Pa /var/www/conf/bgplg.foot 125Optional 126.Nm 127HTML footer. 128.It Pa /var/www/logs/bgpd.rsock 129Position of the second, restricted, control socket of 130.Xr bgpd 8 . 131.El 132.Pp 133The following statically linked executables have been installed into 134the 135.Xr chroot 2 136environment of the 137.Xr httpd 8 138server. 139To enable the corresponding functionality, use the 140.Xr chmod 1 141utility to manually set the file permission mode to 0555 or anything 142appropriate. 143.Pp 144.Bl -tag -width "/var/www/bin/traceroute6XX" -compact 145.It Pa /var/www/cgi-bin/bgplg 146The 147.Nm 148CGI executable. 149.It Pa /var/www/bin/bgpctl 150The 151.Xr bgpctl 8 152program used to query information from 153.Xr bgpd 8 154.It Pa /var/www/bin/ping 155The 156.Xr ping 8 157program used to send ICMP ECHO_REQUEST packets to network hosts. 158Requires the set-user-ID bit, set the permission mode to 4555. 159.It Pa /var/www/bin/ping6 160The 161.Xr ping6 8 162program used to send ICMPv6 ICMP6_ECHO_REQUEST packets to network hosts. 163Requires the set-user-ID bit, set the permission mode to 4555. 164.It Pa /var/www/bin/traceroute 165The 166.Xr traceroute 8 167program used to print the route packets take to network hosts. 168Requires the set-user-ID bit, set the permission mode to 4555. 169.It Pa /var/www/bin/traceroute6 170The 171.Xr traceroute6 8 172program used to print the route packets take to 173.Xr inet6 4 174network hosts. 175Requires the set-user-ID bit, set the permission mode to 4555. 176.El 177.Sh SEE ALSO 178.Xr bgpctl 8 , 179.Xr bgpd 8 , 180.Xr bgplgsh 8 , 181.Xr httpd 8 182.Sh HISTORY 183The 184.Nm 185program first appeared in 186.Ox 4.1 . 187The initial implementation was done in 2005 for DE-CIX, the German 188commercial internet exchange point. 189.Sh AUTHORS 190The 191.Nm 192program was written by 193.An Reyk Floeter Aq reyk@vantronix.net . 194.Sh CAVEATS 195To prevent commands from running endlessly, 196.Nm 197will kill the corresponding processes after a hard limit of 60 seconds. 198For example, this can take effect when using 199.Xr traceroute 8 200with blackholed or bad routes. 201