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