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