Annotation of www/porting.html, Revision 1.11
1.1 marc 1: <html>
2: <head>
3: <meta http-equiv="Content-Type"
4: content="text/html; charset=iso-8859-1">
5: <meta name="resource-type"
6: content="document">
7: <meta name="description"
8: CONTENT="How to make an OpenBSD port">
9: <meta name="keywords"
10: content="openbsd,ports">
11: <meta name="distribution"
12: content="global">
13: <meta name="copyright"
14: content="This document copyright 1997 by the OpenBSD project">
15: <title>Building an OpenBSD port</title>
16: <link rev="made" HREF="mailto:www@openbsd.org">
17: </head>
18: <body text="#000000" bgcolor="#FFFFFF" link="#23238E">
1.6 pauls 19: <img height=30 width=141 src=images/smalltitle.gif alt="[OpenBSD]" >
1.1 marc 20:
1.3 marc 21: <h2><font color=#e00000>Building an OpenBSD port</font></h2>
1.1 marc 22:
23: So you've just compiled your favorite software package on your
24: OpenBSD machine and you want to share your effort by turning
25: it into a standard port. What to do?
26: <p>
1.9 marc 27: First look at the porting information on this page. Then check
28: out the referenced documents, especially the OpenBSD porting
29: checklist.
1.1 marc 30: <p>
1.9 marc 31: Test, then re-test, and finally test again!
32: <p>
33: Submit the port. Create a gzipped tarball of the port directory.
34: You can then either place it on a public FTP or HTTP server, sending
35: its address to <a href=mailto:ports@openbsd.org>ports@openbsd.org</a>
36: or send the port mime encoded to the same address. Pick whichever
37: method works best for you.
1.1 marc 38: <p>
39: <h3><font color=#0000e0>Available Porting Information</font></h3>
40: <ul>
41: <li>The file <code>/usr/share/mk/bsd.port.mk</code>. This is the
42: system ports makefile included at the end of each individual
43: port makefile. Read the comments at the start of the makefile.
44: They do a good job of describing the available make options.
45: <li>The
46: <a href="http://www.netbsd.org/Documentation/netbsd/Packages.txt">NetBSD
47: Package System</a> documentation. This document describes NetBSD's
48: version of the FreeBSD ports system and is quite helpful.
1.8 marc 49: <li>Section 19.2.5 of the
1.1 marc 50: <a href="http://www.freebsd.org/handbook/porting.html">FreeBSD
51: Handbook</a>. This is the FreeBSD porting bible.
1.9 marc 52: <li>OpenBSD porting <a href="checklist.html">checklist</a>.
1.1 marc 53: <li>The OpenBSD ports mailing list,
54: <a href="mailto:ports@openbsd.org">ports@OpenBSD.ORG</a>.
55: </ul>
56: <h3><font color=#0000e0>OpenBSD Porting Policy</font></h3>
57: <ul>
58: <li>OpenBSD does NOT use /usr/local/etc/rc.d.<br>
1.7 espie 59: <code>/usr/local</code> is often shared between several machines
1.8 marc 60: thanks to NFS. For this reason, configuration files that are specific
61: to a given machine can't be stored under <code>/usr/local</code>,
62: <code>/etc</code> is the central repository for per machine
63: configuration files. Moreover, OpenBSD policy is to never update
64: files under <code>/etc</code> automatically. Ports that need some
65: specific boot setup should advise the administrator about what to do
66: instead of blindly installing files.
1.1 marc 67: <li>OpenBSD does NOT compress man pages.
68: <li>OpenBSD does NOT require <code>-lcrypt</code>.<br>
69: DES encryption is part of the standard <code>libc</code>.
1.10 espie 70: <li>OpenBSD is strongly security-oriented. You should read and understand
71: this page's <a href="#security">security section</a>.
72: <li>Be sure to add the <code>$</code><code>OpenBSD$</code> CVS tag to
73: the Makefile. If importing a port from another system be sure to
74: leave their tag in the Makefile, too. However, replace the FreeBSD
75: <code>$</code><code>Id$</code> tag with the
76: <code>$</code><code>FreeBSD$</code> tag.
77: <li>The goal is to get all ported applications to support OpenBSD. To
78: achieve this goal you <strong>must</strong> feed any OpenBSD patches
79: back to the application maintainer.
80: </ul>
81: <a name=security>
82: <h3><font color=#0000e0>Security recommendations</font></h3>
83: There are many security problems to worry about. If
1.2 marc 84: you are not absolutely sure of what you are doing please request
1.1 marc 85: help from the <a href="mailto:ports@openbsd.org">ports</a> mailing
86: list.
1.10 espie 87:
88: <ul>
89: <li>Do <emph>not</emph> use alpha or beta code when preparing a port. Use the
90: latest regular or patch release.
91:
1.1 marc 92: <li>Any software to be installed as a server should be scanned
93: for buffer overflows, especially unsafe use of
94: <code>strcat/strcpy/strcmp/sprintf</code>. In general,
95: <code>sprintf</code> should be replaced with <code>snprintf</code>.
1.10 espie 96:
97: <li>Never use filenames when you need security. There are numerous race
98: conditions where you don't have proper control. For instance, an attacker
99: who already has user privileges on your machines may replace files in
100: <code>/tmp</code> with symbolic links to more strategic files, such as
101: <code>/etc/passwd</code>. For instance, the bsd linker warns about
102: <code>mktemp</code> uses. <strong>These must be fixed</strong>.
103: This is not quite as simple as <code>s/mktemp/mkstemp/g</code>.
104:
105: <li>Just because you can read it doesn't mean you should. A well-known hole
106: of this nature was the <code>startx</code> problem. As a setuid program,
107: you could launch startx with any file as a script. If the file was not
108: a valid shell script, a syntax error message would follow, along with the
109: first line of the offending file, without any further permission check.
110: Pretty handy to grab the first line of a shadow passwd file, considering
111: these often start with root entry. Once again, don't trust filenames:
112: open your file, and do an <code>fstat</code> on the open descriptor to
113: check the actual rights.
114:
115: <li>Don't use anything that forks a shell in setuid programs before dropping
116: your privileges. This includes <code>popen</code> and <code>system</code>.
117: Use <code>fork</code>, <code>pipe</code> and <code>execve</code> instead.
118:
119: <li>Pass open descriptors instead of filenames to other programs to avoid race
120: conditions. Even if a program does not accept file descriptors, you can
121: still use <code>/dev/fd/0</code>.
122:
123: <li>Access rights are attached to file descriptors. If you need setuid rights
124: to open a file, open that file, then drop your privileges. You can still
125: access the open descriptor, but you have less to worry about. This is
126: double-edged: even after dropping privileges, you should still watch out
127: for those descriptors.
128:
129: <li>Avoid root setuid as much as you can. Basically, root can do anything,
130: but root rights are very rarely needed, except maybe to create socket ports with
131: a number under 1024. It is arguably better to keep that under <code>inetd</code>
132: control and just add the relevant entries to <code>inetd.conf</code>.
133: You must know the appropriate magic for writing daemons to achieve that.
134: It could be argued that you have no business writing setuid programs if you don't
135: know how to do that.
136:
137: <li>Use setgid instead of setuid. Apart from those specific files needed by setgid
138: programs, most files are not group-writable. Hence, a security problem in a setgid
139: program won't compromise your system as much: with only group rights, the worst
140: an intruder will be able to do is hack a games score table or some such.
141: See the <code>xkobo</code> port for an instance of such a change.
142:
143: <li>Don't trust group-writable files. Even though they are audited, setgid programs
144: are not perceived as important potential security holes. Hence stuff they can tamper
145: with shouldn't be considered sensitive information.
146:
147: <li>Don't trust your environment ! This involves simple things such as your <code>PATH</code>
148: (never use <code>system</code> with an unqualified name), but also more subtle items
149: such as your locale, timezone, termcap, and so on. Be aware of transitivity: even though you're
150: taking full precautions, programs you call directly won't necessarily. <strong>Never</strong>
151: use <code>system</code> in privileged programs, build your command line, a controlled environment,
152: and call <code>execvp</code> directly. The <code>perlsec</code> man page is a good tutorial on
153: such problems.
154:
155: <li>Never used setuid shell-scripts. These are inherently insecure. Wrap them into some C code
156: that ensures a proper environment. On the other hand, OpenBSD features secure perl scripts.
157:
158: <li>Beware the dynamic loader. If you are running setuid, it will only use trusted libraries
159: that were scanned with ldconfig. Setgid is not enough.
160:
161: <li>Dynamic libraries are tricky. C++ code sets a similar problem. Basically, libraries may take
162: some action based upon your environment before your main program even gets to check its setuid
163: status. OpenBSD <code>issetugid</code> addresses this problem, from the library writer point
164: of view. Don't try to port libraries unless you understand this issue thoroughly.
165: </ul>
166: <h3><font color=#0000e0>Generic porting hints</font></h3>
167: <ul>
168: <li><code>__OpenBSD__</code> should be used sparingly, if at all.
169: Constructs that look like
170: <pre>
171: #if defined(__NetBSD__) || defined(__FreeBSD__)
172: </pre>
173: are often inappropriate. Don't add blindly <code>__OpenBSD__</code>
174: to it. Instead, try to figure out what's going on, and what actual
175: feature is needed. Manual pages are often useful, as they include
176: historic comments, stating when a particular feature was incorporated
177: into BSD. Checking the numeric value of <code>BSD</code> against known
178: releases is often the right way. See
179: <a href="http://www.netbsd.org/Documentation/netbsd/Packages.txt">the NetBSD package guide</a>
180: for more information.
181: <li>Defining <code>BSD</code> is a bad idea. Try to include <code>sys/param.h</code>.
182: This not only defines <code>BSD</code>, it also gives it a proper value.
183: The right code fragment should look like:
184: <pre>
185: #if (defined(__unix__) || defined(unix)) && !defined(USG)
186: #include <sys/param.h>
187: #endif
188: </pre>
189: <li>Test for features, not for specific OSes. In the long run, it is much
190: better to test whether <code>tcgetattr</code> works than whether you're running
191: under BSD 4.3 or later, or SystemVR4. These kind of tests just confuse the
192: issue. The way to go about it is, for instance, to test for one particular
193: system, set up a slew of <code>HAVE_TCGETATTR</code> defines, then proceed to
194: the next system. This technique separates features tests from specific OSes.
195: In a hurry, another porter can just add the whole set of <code>-DHAVE_XXX</code>
196: defines to the Makefile. One may also write or add to a configure script to check for
197: that feature and add it automatically. As an example not to follow, check nethack 3.2.2
198: source: it assumes loads of things based on the system type. Most of these assumptions
199: are obsolete and no longer reflect reality: POSIX functions are more useful than older
200: BSD versus SystemV differences, to the point that some traditional bsd functions are
201: now only supported through compatibility libraries.
202:
203: <li>Avoid include files that include other includes that... First, because
204: this is inefficient. Your project will end up including a file that includes
205: everything. Also, because it makes some problems difficult to correct. It
206: becomes harder to <em>not</em> include one particular file at a given point.
207:
208: <li>Avoid bizarre macro tricks. Undefining a macro that was defined by a
209: header file is a bad idea. Defining macros to get some specific behavior
210: from an include file is also a bad idea: compilation modes should be global.
211: If you want POSIX behavior, say so, and <code>#define POSIX_C_SOURCE</code>
212: throughout the whole project, not when you feel like it.
213:
214: <li>Don't ever write system function prototypes. All modern systems,
215: OpenBSD included, have a standard location for these prototypes. Likely
216: places include <code>unistd.h</code>, <code>fcntl.h</code> or <code>termios.h</code>.
217: The man page frequently states where the prototype lies. You might need
218: another slew of <code>HAVE_XXX</code> macros to procure the right file.
219: Don't worry about including the same file twice, include files have guards
220: that prevent all kinds of nastiness.<br>
221: If some broken system needs you to write the prototype, don't impose
222: on all other systems. Roll-your-own prototypes will break because they may
223: use types that are equivalent on your system, but are not portable to other
224: systems (<code>unsigned long</code> instead of <code>size_t</code>), or get some
225: <code>const</code> status wrong. Also, some compilers, such as OpenBSD's own gcc,
226: are able to do a better job with some very frequent functions such as
227: <code>strlen</code> if you include the right header file.
228:
229: <li>Don't use the name of a standard system function for anything else.
230: If you want to write your own function, give it its own name, and call that
231: function everywhere. If you wish to revert to the default system function,
232: you just need to comment your code out, and define your own name to the
233: system function. Don't do it the other way round. Code should look like this
234: <pre>
235: /* prototype part */
236: #ifdef USE_OWN_GCVT
237: char *foo_gcvt(double number, size_t ndigit, char *buf);
238: #else
239: /* include correct file */
240: #include <stdlib.h>
241: /* use system function */
242: #define foo_gcvt gcvt
243: #endif
244:
245: /* definition part */
246: #ifdef USE_OWN_GCVT
247: char *foo_gcvt(double number, size_t ndigit, char *buf)
248: {
249: /* proper definition */
250: }
251:
252: /* typical use */
253: s = foo_gcvt(n, 15, b);
254: </pre>
1.1 marc 255: </ul>
256: <h3><font color=#0000e0>Other Helpful Hints</font></h3>
257: <ul>
258: <li>Do not assume <code>/usr/local/bin</code> or
259: <code>/usr/X11R6/bin</code> is in the installers path. A good
260: way to verify this is to create and install your port while
261: running as <code>root</code> with only <code>/bin</code> and
262: <code>/usr/bin</code> in your path.
263: <li>Do NOT generate shared libraries for <code>${MACHINE_ARCH} ==
264: alpha</code>
265: <li>In OpenBSD <code>curses.h/libcurses/libtermlib</code> are the
266: ``new curses''. Change:<br>
267: <code>ncurses.h ==> curses.h</code><br>
268: <code>-lncurses ==> -lcurses</code><br>
1.11 ! millert 269: ``old (BSD) curses'' is available by defining <code>_USE_OLD_CURSES_</code>
! 270: before including <code>curses.h</code> (usually in a Makefile) and
! 271: linking with <code>-lcurses</code>.
! 272: <li>In OpenBSD, terminal discipline has been upgraded from the older BSD
! 273: <code>sgtty</code> to the newer POSIX <code>tcgetattr</code> family.
1.10 espie 274: Avoid the older style in new code. Some code may define <code>tcgetattr</code>
1.11 ! millert 275: to be a synonym for the older <code>sgtty</code>, but this is at best a stopgap
1.10 espie 276: measure on OpenBSD. The <code>xterm</code> source code is a very good example of
277: what not to do.
278: Try to get your system functionality right: you want a type that remembers
279: the state of your terminal (possible typedef), you want a function that
280: extracts the current state, and a function that sets the new state.
281: Functions that modify this state are more difficult, as they tend to vary
282: depending upon the system. Also, don't forget that you will have to handle
283: cases where you are not connected to the terminal, and that you need to
284: handle signals: not only termination, but also getting put in the background
285: you should leave your terminal in a sane state. Do your tests under an
286: older shell, such as sh, which does not reset the terminal in any way at
287: program's termination.
1.11 ! millert 288: <li>The newer termcap/terminfo and curses, as included with OpenBSD, include standard sequences
1.10 espie 289: for controlling color terminals. You should use these if possible, reverting
290: to standard ANSI color sequences on other systems. However, some terminal descriptions
291: have not been updated yet, and you may need to be able to specify these sequences manually.
292: This is the way vim5.1 handles it. This is not strictly necessary. Except for privileged
293: programs, it is generally possible to override a termcap definition through the
294: <code>TERMCAP</code> variable and get it to work properly.
295: <li>Signal semantics are tricky, and vary from one system to another. Use <code>sigaction</code>
296: to ensure a specific semantics, along with other system calls referenced in its manpage.
1.1 marc 297: </ul>
298: <hr>
1.6 pauls 299: <a href="index.html"><img height=24 width=24 src=back.gif border=0 alt=OpenBSD></a>
1.1 marc 300: <a href=mailto:www@openbsd.org>www@openbsd.org</a>
1.11 ! millert 301: <br><small>$OpenBSD: porting.html,v 1.10 1998/08/13 23:11:18 espie Exp $</small>
1.1 marc 302: </body>
303: </html>