xref: /openbsd/usr.bin/bgplg/bgplg.8 (revision e5dd7070) 
1.\"	$OpenBSD: bgplg.8,v 1.16 2016/12/14 14:38:42 reyk Exp $
2.\"
3.\" Copyright (c) 2005, 2006, 2013 Reyk Floeter <reyk@openbsd.org>
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: December 14 2016 $
18.Dt BGPLG 8
19.Os
20.Sh NAME
21.Nm bgplg
22.Nd looking glass for the OpenBSD Border Gateway Protocol daemon
23.Sh SYNOPSIS
24.Nm bgplg
25.Sh DESCRIPTION
26The
27.Nm
28CGI program is a looking glass for the
29.Xr bgpd 8
30Border Gateway Protocol daemon.
31The looking glass will provide a simple web interface with read-only
32access to a restricted set of
33.Xr bgpd 8
34and system status information, which is typically used on route
35servers by Internet Service Providers (ISPs) and Internet eXchange
36points (IXs).
37It is intended to be used in a
38.Xr chroot 2
39environment in
40.Pa /var/www .
41.Pp
42.Nm
43is disabled by default.
44It requires four steps to enable the looking glass:
45.Bl -enum
46.It
47Update the file permission mode to allow the execution of the
48.Nm
49CGI program and the additional statically linked programs that have
50been installed into the
51.Xr chroot 2
52environment.
53.Pp
54For example,
55to allow execution of
56.Nm
57and the statically-linked version of
58.Xr bgpctl 8 :
59.Bd -literal -offset indent
60# chmod 0555 /var/www/cgi-bin/bgplg
61# chmod 0555 /var/www/bin/bgpctl
62.Ed
63.Pp
64External commands like
65.Xr ping 8
66and others will be hidden from the looking glass command
67list unless given the correct permissions.
68See the
69.Sx FILES
70section below for the list of installed programs.
71.It
72The programs
73.Xr ping 8 ,
74.Xr ping6 8 ,
75.Xr traceroute 8
76and
77.Xr traceroute6 8
78will require a copy of the resolver configuration file
79.Xr resolv.conf 5
80in the
81.Xr chroot 2
82environment for optional host name lookups.
83.Bd -literal -offset indent
84# mkdir /var/www/etc
85# cp /etc/resolv.conf /var/www/etc
86.Ed
87.It
88Start the Border Gateway Protocol daemon with a second,
89restricted, control socket that can be used
90from within the
91.Xr chroot 2
92environment.
93See
94.Xr bgpd.conf 5
95for more information.
96.Pp
97For example,
98add the following to
99.Pa /etc/bgpd.conf
100to have
101.Xr bgpd 8
102open a second, restricted, control socket:
103.Pp
104.Dl socket \&"/var/www/run/bgpd.rsock\&" restricted
105.It
106Start the
107.Xr httpd 8
108and
109.Xr slowcgi 8
110servers after configuring the related
111.Ic server
112section in
113.Xr httpd.conf 5 .
114For example:
115.Bd -literal -offset indent
116ext_addr="0.0.0.0"
117
118server "lg.example.net" {
119	listen on $ext_addr port 80
120	location "/cgi-bin/*" {
121		fastcgi
122		root ""
123	}
124}
125.Ed
126.El
127.Sh FILES
128.Bl -tag -width "/var/www/conf/bgplg.headXX" -compact
129.It Pa /var/www/conf/bgplg.css
130Optional
131.Nm
132CSS style sheet.
133.It Pa /var/www/conf/bgplg.head
134Optional
135.Nm
136HTML header.
137.It Pa /var/www/conf/bgplg.foot
138Optional
139.Nm
140HTML footer.
141.It Pa /var/www/run/bgpd.rsock
142Position of the second, restricted, control socket of
143.Xr bgpd 8 .
144.El
145.Pp
146The following statically linked executables have been installed into
147the
148.Xr chroot 2
149environment of the
150.Xr httpd 8
151server.
152To enable the corresponding functionality, use the
153.Xr chmod 1
154utility to manually set the file permission mode to 0555 or anything
155appropriate.
156Some of these executables need the set-user-ID bit,
157so they should be mounted on a filesystem
158without the
159.Ic nosuid
160option.
161.Pp
162.Bl -tag -width "/var/www/bin/traceroute6XX" -compact
163.It Pa /var/www/cgi-bin/bgplg
164The
165.Nm
166CGI executable.
167.It Pa /var/www/bin/bgpctl
168The
169.Xr bgpctl 8
170program used to query information from
171.Xr bgpd 8
172.It Pa /var/www/bin/ping
173The
174.Xr ping 8
175program used to send ICMP ECHO_REQUEST packets to network hosts.
176Requires the set-user-ID bit, set the permission mode to 4555.
177.It Pa /var/www/bin/ping6
178The
179.Xr ping6 8
180program used to send ICMPv6 ICMP6_ECHO_REQUEST packets to network hosts.
181Requires the set-user-ID bit, set the permission mode to 4555.
182.It Pa /var/www/bin/traceroute
183The
184.Xr traceroute 8
185program used to print the route packets take to network hosts.
186Requires the set-user-ID bit, set the permission mode to 4555.
187.It Pa /var/www/bin/traceroute6
188The
189.Xr traceroute6 8
190program used to print the route packets take to
191.Xr inet6 4
192network hosts.
193Requires the set-user-ID bit, set the permission mode to 4555.
194.El
195.Sh SEE ALSO
196.Xr bgpctl 8 ,
197.Xr bgpd 8 ,
198.Xr bgplgsh 8 ,
199.Xr httpd 8 ,
200.Xr slowcgi 8
201.Sh HISTORY
202The
203.Nm
204program first appeared in
205.Ox 4.1 .
206The initial implementation was done in 2005 for DE-CIX, the German
207commercial internet exchange point.
208.Sh AUTHORS
209The
210.Nm
211program was written by
212.An Reyk Floeter Aq Mt reyk@openbsd.org .
213.Sh CAVEATS
214To prevent commands from running endlessly,
215.Nm
216will kill the corresponding processes after a hard limit of 60 seconds.
217For example, this can take effect when using
218.Xr traceroute 8
219with blackholed or bad routes.
220