Annotation of src/usr.bin/bgplg/bgplg.8, Revision 1.14
1.14 ! reyk 1: .\" $OpenBSD: bgplg.8,v 1.13 2013/09/03 20:36:02 reyk Exp $
1.1 reyk 2: .\"
1.13 reyk 3: .\" Copyright (c) 2005, 2006, 2013 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.14 ! reyk 17: .Dd $Mdocdate: September 3 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.13 reyk 108: Start the
1.14 ! reyk 109: .Xr httpd 8
1.13 reyk 110: and
111: .Xr slowcgi 8
112: servers after configuring the related
113: .Ic server
114: section in
1.14 ! reyk 115: .Xr httpd.conf 5 .
1.13 reyk 116: For example:
117: .Bd -literal -offset indent
1.14 ! reyk 118: ext_addr="0.0.0.0"
! 119:
! 120: server "lg.example.net" {
! 121: listen on $ext_addr port 80
! 122: location "/cgi-bin/*" {
! 123: fastcgi
! 124: root ""
! 125: }
1.13 reyk 126: }
127: .Ed
1.1 reyk 128: .El
129: .Sh FILES
130: .Bl -tag -width "/var/www/conf/bgplg.headXX" -compact
131: .It Pa /var/www/conf/bgplg.css
132: Optional
133: .Nm
134: CSS style sheet.
135: .It Pa /var/www/conf/bgplg.head
136: Optional
137: .Nm
138: HTML header.
139: .It Pa /var/www/conf/bgplg.foot
140: Optional
141: .Nm
142: HTML footer.
1.11 florian 143: .It Pa /var/www/run/bgpd.rsock
1.1 reyk 144: Position of the second, restricted, control socket of
145: .Xr bgpd 8 .
146: .El
147: .Pp
148: The following statically linked executables have been installed into
149: the
150: .Xr chroot 2
151: environment of the
1.14 ! reyk 152: .Xr httpd 8
1.1 reyk 153: server.
154: To enable the corresponding functionality, use the
155: .Xr chmod 1
1.2 reyk 156: utility to manually set the file permission mode to 0555 or anything
1.1 reyk 157: appropriate.
158: .Pp
1.5 sthen 159: .Bl -tag -width "/var/www/bin/traceroute6XX" -compact
1.1 reyk 160: .It Pa /var/www/cgi-bin/bgplg
161: The
162: .Nm
163: CGI executable.
164: .It Pa /var/www/bin/bgpctl
165: The
166: .Xr bgpctl 8
167: program used to query information from
168: .Xr bgpd 8
169: .It Pa /var/www/bin/ping
170: The
171: .Xr ping 8
172: program used to send ICMP ECHO_REQUEST packets to network hosts.
1.2 reyk 173: Requires the set-user-ID bit, set the permission mode to 4555.
1.5 sthen 174: .It Pa /var/www/bin/ping6
175: The
176: .Xr ping6 8
177: program used to send ICMPv6 ICMP6_ECHO_REQUEST packets to network hosts.
178: Requires the set-user-ID bit, set the permission mode to 4555.
1.1 reyk 179: .It Pa /var/www/bin/traceroute
180: The
181: .Xr traceroute 8
182: program used to print the route packets take to network hosts.
1.5 sthen 183: Requires the set-user-ID bit, set the permission mode to 4555.
184: .It Pa /var/www/bin/traceroute6
185: The
186: .Xr traceroute6 8
187: program used to print the route packets take to
188: .Xr inet6 4
189: network hosts.
1.2 reyk 190: Requires the set-user-ID bit, set the permission mode to 4555.
1.1 reyk 191: .El
192: .Sh SEE ALSO
193: .Xr bgpctl 8 ,
194: .Xr bgpd 8 ,
195: .Xr bgplgsh 8 ,
1.14 ! reyk 196: .Xr httpd 8 ,
1.13 reyk 197: .Xr slowcgi 8
1.1 reyk 198: .Sh HISTORY
199: The
200: .Nm
201: program first appeared in
202: .Ox 4.1 .
203: The initial implementation was done in 2005 for DE-CIX, the German
204: commercial internet exchange point.
205: .Sh AUTHORS
206: The
207: .Nm
208: program was written by
1.12 schwarze 209: .An Reyk Floeter Aq Mt reyk@openbsd.org .
1.3 reyk 210: .Sh CAVEATS
211: To prevent commands from running endlessly,
212: .Nm
213: will kill the corresponding processes after a hard limit of 60 seconds.
214: For example, this can take effect when using
215: .Xr traceroute 8
216: with blackholed or bad routes.
![[BACK]](/icons/back.gif){kind=icon}
Return to bgplg.8 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / bgplg