Annotation of src/usr.bin/bgplg/bgplg.8, Revision 1.4
1.4 ! jmc 1: .\" $OpenBSD: bgplg.8,v 1.3 2006/12/12 14:36:14 reyk Exp $
1.1 reyk 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: .\"
1.4 ! jmc 17: .Dd $Mdocdate$
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: See the
56: .Sx FILES
57: section below for the list of installed programs.
58: .Pp
59: For example,
60: to allow execution of
61: .Nm
62: and the statically-linked version of
63: .Xr bgpctl 8
64: (disabled commands like
65: .Xr ping 8
66: and
67: .Xr traceroute 8
68: will be hidden from looking glass command list):
69: .Bd -literal -offset indent
1.2 reyk 70: # chmod 0555 /var/www/cgi-bin/bgplg
71: # chmod 0555 /var/www/bin/bgpctl
1.1 reyk 72: .Ed
73: .It
74: The programs
75: .Xr ping 8
76: and
77: .Xr traceroute 8
78: will require a copy of the resolver configuration file
79: .Xr resolv.conf 5
80: in the
81: .Xr chroot 2
82: environment 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
88: Start the Border Gateway Protocol daemon with a second,
89: restricted, control socket that can be used
90: from within the
91: .Xr chroot 2
92: environment.
93: See
94: .Xr bgpd 8
95: for more information.
96: .Pp
97: For example,
98: set the following in
99: .Pa /etc/rc.conf.local
100: to start
101: .Xr bgpd 8
102: using the second, restricted, control socket:
103: .Pp
104: .Dl bgpd_flags=\&"-r /var/www/logs/bgpd.rsock\&"
105: .Pp
106: .It
107: Start the Apache Hypertext Transfer Protocol Server.
108: See
109: .Xr httpd 8
110: for more information.
111: .El
112: .Sh FILES
113: .Bl -tag -width "/var/www/conf/bgplg.headXX" -compact
114: .It Pa /var/www/conf/bgplg.css
115: Optional
116: .Nm
117: CSS style sheet.
118: .It Pa /var/www/conf/bgplg.head
119: Optional
120: .Nm
121: HTML header.
122: .It Pa /var/www/conf/bgplg.foot
123: Optional
124: .Nm
125: HTML footer.
126: .It Pa /var/www/logs/bgpd.rsock
127: Position of the second, restricted, control socket of
128: .Xr bgpd 8 .
129: .El
130: .Pp
131: The following statically linked executables have been installed into
132: the
133: .Xr chroot 2
134: environment of the
135: .Xr httpd 8
136: server.
137: To enable the corresponding functionality, use the
138: .Xr chmod 1
1.2 reyk 139: utility to manually set the file permission mode to 0555 or anything
1.1 reyk 140: appropriate.
141: .Pp
142: .Bl -tag -width "/var/www/bin/tracerouteXX" -compact
143: .It Pa /var/www/cgi-bin/bgplg
144: The
145: .Nm
146: CGI executable.
147: .It Pa /var/www/bin/bgpctl
148: The
149: .Xr bgpctl 8
150: program used to query information from
151: .Xr bgpd 8
152: .It Pa /var/www/bin/ping
153: The
154: .Xr ping 8
155: program used to send ICMP ECHO_REQUEST packets to network hosts.
1.2 reyk 156: Requires the set-user-ID bit, set the permission mode to 4555.
1.1 reyk 157: .It Pa /var/www/bin/traceroute
158: The
159: .Xr traceroute 8
160: program used to print the route packets take to network hosts.
1.2 reyk 161: Requires the set-user-ID bit, set the permission mode to 4555.
1.1 reyk 162: .El
163: .Sh SEE ALSO
164: .Xr bgpctl 8 ,
165: .Xr bgpd 8 ,
166: .Xr bgplgsh 8 ,
167: .Xr httpd 8
168: .Sh HISTORY
169: The
170: .Nm
171: program first appeared in
172: .Ox 4.1 .
173: The initial implementation was done in 2005 for DE-CIX, the German
174: commercial internet exchange point.
175: .Sh AUTHORS
176: The
177: .Nm
178: program was written by
179: .An Reyk Floeter Aq reyk@vantronix.net .
1.3 reyk 180: .Sh CAVEATS
181: To prevent commands from running endlessly,
182: .Nm
183: will kill the corresponding processes after a hard limit of 60 seconds.
184: For example, this can take effect when using
185: .Xr traceroute 8
186: with blackholed or bad routes.