Annotation of src/usr.bin/bgplg/bgplg.8, Revision 1.6
1.6 ! sthen 1: .\" $OpenBSD: bgplg.8,v 1.5 2010/04/02 22:44:40 sthen 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.6 ! sthen 17: .Dd $Mdocdate: April 2 2010 $
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
96: .Xr bgpd 8
97: for more information.
98: .Pp
99: For example,
100: set the following in
101: .Pa /etc/rc.conf.local
102: to start
103: .Xr bgpd 8
104: using the second, restricted, control socket:
105: .Pp
106: .Dl bgpd_flags=\&"-r /var/www/logs/bgpd.rsock\&"
107: .Pp
108: .It
109: Start the Apache Hypertext Transfer Protocol Server.
110: See
111: .Xr httpd 8
112: for 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
117: Optional
118: .Nm
119: CSS style sheet.
120: .It Pa /var/www/conf/bgplg.head
121: Optional
122: .Nm
123: HTML header.
124: .It Pa /var/www/conf/bgplg.foot
125: Optional
126: .Nm
127: HTML footer.
128: .It Pa /var/www/logs/bgpd.rsock
129: Position of the second, restricted, control socket of
130: .Xr bgpd 8 .
131: .El
132: .Pp
133: The following statically linked executables have been installed into
134: the
135: .Xr chroot 2
136: environment of the
137: .Xr httpd 8
138: server.
139: To enable the corresponding functionality, use the
140: .Xr chmod 1
1.2 reyk 141: utility to manually set the file permission mode to 0555 or anything
1.1 reyk 142: appropriate.
143: .Pp
1.5 sthen 144: .Bl -tag -width "/var/www/bin/traceroute6XX" -compact
1.1 reyk 145: .It Pa /var/www/cgi-bin/bgplg
146: The
147: .Nm
148: CGI executable.
149: .It Pa /var/www/bin/bgpctl
150: The
151: .Xr bgpctl 8
152: program used to query information from
153: .Xr bgpd 8
154: .It Pa /var/www/bin/ping
155: The
156: .Xr ping 8
157: program used to send ICMP ECHO_REQUEST packets to network hosts.
1.2 reyk 158: Requires the set-user-ID bit, set the permission mode to 4555.
1.5 sthen 159: .It Pa /var/www/bin/ping6
160: The
161: .Xr ping6 8
162: program used to send ICMPv6 ICMP6_ECHO_REQUEST packets to network hosts.
163: Requires the set-user-ID bit, set the permission mode to 4555.
1.1 reyk 164: .It Pa /var/www/bin/traceroute
165: The
166: .Xr traceroute 8
167: program used to print the route packets take to network hosts.
1.5 sthen 168: Requires the set-user-ID bit, set the permission mode to 4555.
169: .It Pa /var/www/bin/traceroute6
170: The
171: .Xr traceroute6 8
172: program used to print the route packets take to
173: .Xr inet6 4
174: network hosts.
1.2 reyk 175: Requires the set-user-ID bit, set the permission mode to 4555.
1.1 reyk 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
183: The
184: .Nm
185: program first appeared in
186: .Ox 4.1 .
187: The initial implementation was done in 2005 for DE-CIX, the German
188: commercial internet exchange point.
189: .Sh AUTHORS
190: The
191: .Nm
192: program was written by
193: .An Reyk Floeter Aq reyk@vantronix.net .
1.3 reyk 194: .Sh CAVEATS
195: To prevent commands from running endlessly,
196: .Nm
197: will kill the corresponding processes after a hard limit of 60 seconds.
198: For example, this can take effect when using
199: .Xr traceroute 8
200: with blackholed or bad routes.