Annotation of www/porting.html, Revision 1.58
1.20 rohee 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1.1 marc 2: <html>
3: <head>
4: <meta http-equiv="Content-Type"
1.15 espie 5: content="text/html; charset=iso-8859-1">
1.1 marc 6: <meta name="resource-type"
1.15 espie 7: content="document">
1.1 marc 8: <meta name="description"
1.15 espie 9: CONTENT="How to make an OpenBSD port">
1.1 marc 10: <meta name="keywords"
1.15 espie 11: content="openbsd,ports">
1.1 marc 12: <meta name="distribution"
1.15 espie 13: content="global">
1.1 marc 14: <meta name="copyright"
1.58 ! sthen 15: content="This document copyright 1997-2009 by OpenBSD.">
1.1 marc 16: <title>Building an OpenBSD port</title>
17: <link rev="made" HREF="mailto:www@openbsd.org">
18: </head>
19: <body text="#000000" bgcolor="#FFFFFF" link="#23238E">
1.43 jsyn 20: <a href="index.html"><img alt="[OpenBSD]" height="30" width="141" src="images/smalltitle.gif" border="0"></a>
1.1 marc 21:
1.20 rohee 22: <h2><font color="#e00000">Building an OpenBSD port</font></h2>
1.1 marc 23:
24: So you've just compiled your favorite software package on your
25: OpenBSD machine and you want to share your effort by turning
26: it into a standard port. What to do?
27: <p>
1.55 jolan 28: The most important thing to do is to <strong>communicate</strong>.
1.25 espie 29: Ask people on <a href="mailto:ports@openbsd.org">ports@openbsd.org</a>
30: if they are working on the same port. <em>Tell the original software
31: author about it</em>, including problems you may find. If licensing
32: information appears incorrect tell him. If you had to jump through
33: loops to make the port build, tell him what he can fix. If they are
1.32 deraadt 34: only developing on Linux and feel like ignoring the rest of the Unix
1.25 espie 35: world, try to make them change their view.
36: <p>
37: <strong>COMMUNICATION</strong> makes the difference between a successful
1.34 jufi 38: port and a port that will slowly be abandoned by everyone.
1.25 espie 39: <p>
1.9 marc 40: First look at the porting information on this page. Then check
41: out the referenced documents, especially the OpenBSD porting
1.26 espie 42: <a href="checklist.html">checklist</a>.
1.1 marc 43: <p>
1.9 marc 44: Test, then re-test, and finally test again!
45: <p>
1.56 espie 46: OpenBSD now fully supports updates. This means that
47: <a href="porting/update.html">quite a few issues</a>
48: must be taken into account.
49: <p>
1.9 marc 50: Submit the port. Create a gzipped tarball of the port directory.
51: You can then either place it on a public FTP or HTTP server, sending
1.20 rohee 52: its address to <a href="mailto:ports@openbsd.org">ports@openbsd.org</a>
1.9 marc 53: or send the port mime encoded to the same address. Pick whichever
54: method works best for you.
1.57 espie 55: <p>
56: Porting some new software takes time. Maintaining it over time is harder.
57: It is quite okay to port software, and let other people handle it
58: afterwards. It is also okay to help other people update and maintain
59: other ports, as long as you communicate to avoid doing the same things
60: twice.
61: <p>
62: In the OpenBSD culture, <code>MAINTAINER</code>ship is not a status item,
63: but a responsibility. We have CVS and comments to give credit to the
64: person who did the work. A port <code>MAINTAINER</code> is something else:
65: a person who assumes responsibility for the working of the port, and is
66: willing to spend some time ensuring it works as best as can be.
1.35 naddy 67:
68: <h3><font color="#0000e0">Index of Porting Documentation</font></h3>
69: <ul>
70: <li><a href="#Avail">Available Porting Information</a></li>
71: <li><a href="#Policy">OpenBSD Porting Policy</a></li>
72: <li><a href="#Security">Security Recommendations</a></li>
73: <li><a href="#Generic">Generic Porting Hints</a></li>
74: <li><a href="#Other">Other Helpful Hints</a></li>
75: </ul>
76:
77: <h3><font color="#0000e0"><a name="Avail">Available Porting Information</a></font></h3>
1.1 marc 78: <ul>
1.38 espie 79: <li>OpenBSD porting <a href="checklist.html">checklist</a>.
1.56 espie 80: <li>OpenBSD ports <a href="porting/update.html">update guidelines</a>.
1.38 espie 81: <li>The man page
1.41 rohee 82: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=bsd.port.mk&sektion=5">bsd.port.mk(5)</a>.
1.38 espie 83: This documents the ports infrastructure makefile that is
84: included at the end of each individual port makefile.
85: There are still a few comments at the start of
1.39 horacio 86: the file itself, but most of the useful information is now
1.38 espie 87: documented.
88: <li>Some differences from other BSD port systems, mostly a summary
89: of <a href="porting/diffs.html">infrastructure differences</a>.
90: <li><a href="porting/libraries.html">Using shared libraries
91: in OpenBSD Ports</a>. The rules there are <strong>very
1.51 espie 92: important</strong> as soon as you use shared libraries.
93: <li><a href="porting/autoconf.html">GNU autoconf specificities</a>,
94: how to deal with it in the context of OpenBSD ports.
95: <li><a href="porting/config.html">Configuration files</a>,
96: one frequent stumbling block for new developers, and the unique
97: tools the OpenBSD ports tree has to deal with these.
1.38 espie 98: <li><a href="audio-port.html">Porting audio applications to OpenBSD</a>.
1.1 marc 99: <li>The
1.13 art 100: <a href="http://www.netbsd.org/Documentation/software/packages.html">
101: NetBSD Package System</a> documentation. This document describes
102: NetBSD's version of the FreeBSD ports system and is quite helpful.
1.33 naddy 103: <li>The
1.42 pvalchev 104: <a href="http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/index.html">FreeBSD
1.33 naddy 105: Porter's Handbook</a>. This is the FreeBSD porting bible.
1.1 marc 106: <li>The OpenBSD ports mailing list,
1.50 alek 107: <a href="mailto:ports@openbsd.org">ports@openbsd.org</a>.
1.1 marc 108: </ul>
1.35 naddy 109: <h3><font color="#0000e0"><a name="Policy">OpenBSD Porting Policy</a></font></h3>
1.1 marc 110: <ul>
1.24 rohee 111: <li>OpenBSD does NOT use <code>/usr/local/etc/rc.d</code>.<br>
1.7 espie 112: <code>/usr/local</code> is often shared between several machines
1.15 espie 113: thanks to NFS. For this reason, configuration files that are specific
114: to a given machine can't be stored under <code>/usr/local</code>,
115: <code>/etc</code> is the central repository for per machine
116: configuration files. Moreover, OpenBSD policy is to never update
117: files under <code>/etc</code> automatically. Ports that need some
118: specific boot setup should advise the administrator about what to do
119: instead of blindly installing files.
1.1 marc 120: <li>OpenBSD does NOT compress man pages.
121: <li>OpenBSD does NOT require <code>-lcrypt</code>.<br>
122: DES encryption is part of the standard <code>libc</code>.
1.46 sturm 123: <li>OpenBSD has a separate namespace for users and groups created by ports.
124: See <code>/usr/ports/infrastructure/db/user.list</code> for details.
1.10 espie 125: <li>OpenBSD is strongly security-oriented. You should read and understand
1.42 pvalchev 126: this page's <a href="#Security">security section</a>.
1.24 rohee 127: <li>Be sure to add the <code>$OpenBSD$</code> CVS tag to
1.10 espie 128: the Makefile. If importing a port from another system be sure to
1.48 xsa 129: leave their tag in the Makefile, too.
1.10 espie 130: <li>The goal is to get all ported applications to support OpenBSD. To
131: achieve this goal you <strong>must</strong> feed any OpenBSD patches
132: back to the application maintainer.
133: </ul>
1.35 naddy 134: <h3><font color="#0000e0"><a name="Security">Security Recommendations</a></font></h3>
1.10 espie 135: There are many security problems to worry about. If
1.2 marc 136: you are not absolutely sure of what you are doing please request
1.1 marc 137: help from the <a href="mailto:ports@openbsd.org">ports</a> mailing
138: list.
1.10 espie 139:
140: <ul>
1.20 rohee 141: <li>Do <em>not</em> use alpha or beta code when preparing a port. Use the
1.10 espie 142: latest regular or patch release.
143:
1.1 marc 144: <li>Any software to be installed as a server should be scanned
145: for buffer overflows, especially unsafe use of
146: <code>strcat/strcpy/strcmp/sprintf</code>. In general,
147: <code>sprintf</code> should be replaced with <code>snprintf</code>.
1.10 espie 148:
1.17 espie 149: <li>Never use filenames instead of true security. There are numerous race
1.10 espie 150: conditions where you don't have proper control. For instance, an attacker
151: who already has user privileges on your machines may replace files in
152: <code>/tmp</code> with symbolic links to more strategic files, such as
1.19 rohee 153: <code>/etc/master.passwd</code>.
1.16 espie 154:
155: <li>For instance, both <code>fopen</code> and <code>freopen</code>
156: <strong>create a new file or open an existing file</strong> for
157: writing. An attacker may create a symbolic link from
1.19 rohee 158: <code>/etc/master.passwd</code> to <code>/tmp/addrpool_dump</code>. The
1.16 espie 159: instant you open it, your password file is hosed. Yes, even with
160: an <code>unlink</code> right before. You only narrow the window
161: of opportunity. Use <code>open</code> with
1.22 rohee 162: <code>O_CREAT|O_EXCL</code> and <code>fdopen</code> instead.
1.15 espie 163:
1.16 espie 164: <li>Another very common problem is the <code>mktemp</code>
1.17 espie 165: function. Heed the warnings of the bsd linker about its uses.
1.15 espie 166: <strong>These must be fixed</strong>.
167: This is not quite as simple as <code>s/mktemp/mkstemp/g</code>. <br>
1.54 ray 168: Refer to
169: <a href="http://www.openbsd.org/cgi-bin/man.cgi?sektion=3&query=mktemp"
170: ><code>mktemp(3)</code></a> for more information.
1.15 espie 171: Correct code using <code>mkstemp</code> includes the source to
172: <code>ed</code> or <code>mail</code>.
173: A rare instance of code that uses <code>mktemp</code> correctly
174: can be found in the <code>rsync</code> port.
1.10 espie 175:
176: <li>Just because you can read it doesn't mean you should. A well-known hole
177: of this nature was the <code>startx</code> problem. As a setuid program,
178: you could launch startx with any file as a script. If the file was not
179: a valid shell script, a syntax error message would follow, along with the
180: first line of the offending file, without any further permission check.
181: Pretty handy to grab the first line of a shadow passwd file, considering
1.12 deraadt 182: these often start with root entry. Do not open your file, and then do
183: an <code>fstat</code> on the open descriptor to check if you should have
1.15 espie 184: been able to open it (or the attacker will play with /dev/rst0 and rewind
1.12 deraadt 185: your tape) -- open it with the correct uid/gid/grouplist set.
1.10 espie 186:
187: <li>Don't use anything that forks a shell in setuid programs before dropping
1.15 espie 188: your privileges. This includes <code>popen</code> and
189: <code>system</code>.
1.10 espie 190: Use <code>fork</code>, <code>pipe</code> and <code>execve</code> instead.
191:
1.15 espie 192: <li>Pass open descriptors instead of filenames to other programs to
193: avoid race conditions. Even if a program does not accept file
194: descriptors, you can still use <code>/dev/fd/0</code>.
1.10 espie 195:
1.15 espie 196: <li>Access rights are attached to file descriptors. If you need setuid rights
1.10 espie 197: to open a file, open that file, then drop your privileges. You can still
198: access the open descriptor, but you have less to worry about. This is
199: double-edged: even after dropping privileges, you should still watch out
200: for those descriptors.
201:
202: <li>Avoid root setuid as much as you can. Basically, root can do anything,
1.15 espie 203: but root rights are very rarely needed, except maybe to create
204: socket ports with a number under 1024. It is arguably better to
205: keep that under <code>inetd</code>
1.10 espie 206: control and just add the relevant entries to <code>inetd.conf</code>.
207: You must know the appropriate magic for writing daemons to achieve that.
1.15 espie 208: It could be argued that you have no business writing setuid programs
209: if you don't know how to do that.
1.10 espie 210:
1.15 espie 211: <li>Use setgid instead of setuid. Apart from those specific files needed
212: by setgid programs, most files are not group-writable. Hence, a
213: security problem in a setgid program won't compromise your system as
214: much: with only group rights, the worst an intruder will be able to
215: do is hack a games score table or some such.
1.10 espie 216: See the <code>xkobo</code> port for an instance of such a change.
217:
1.15 espie 218: <li>Don't trust group-writable files. Even though they are audited,
219: setgid programs are not perceived as important potential security
220: holes. Hence stuff they can tamper with shouldn't be considered
221: sensitive information.
222:
223: <li>Don't trust your environment ! This involves simple things such as
224: your <code>PATH</code> (never use <code>system</code> with an
225: unqualified name, avoid <code>execvp</code>), but also more subtle
226: items such as your locale, timezone, termcap, and so on.
227: Be aware of transitivity: even though you're taking full precautions,
228: programs you call directly won't necessarily. <strong>Never</strong>
229: use <code>system</code> in privileged programs, build your command
230: line, a controlled environment, and call <code>execve</code> directly.
231: The <code>perlsec</code> man page is a good tutorial on such problems.
232:
1.31 jufi 233: <li>Never use setuid shell-scripts. These are inherently insecure.
1.15 espie 234: Wrap them into some C code that ensures a proper environment.
235: On the other hand, OpenBSD features secure perl scripts.
236:
237: <li>Beware the dynamic loader. If you are running setuid, it will only
238: use trusted libraries that were scanned with ldconfig.
239: Setgid is not enough.
240:
241: <li>Dynamic libraries are tricky. C++ code sets a similar problem.
242: Basically, libraries may take some action based upon your environment
243: before your main program even gets to check its setuid status.
244: OpenBSD <code>issetugid</code> addresses this problem, from the
245: library writer point of view. Don't try to port libraries unless you
246: understand this issue thoroughly.
1.10 espie 247: </ul>
1.35 naddy 248: <h3><font color="#0000e0"><a name="Generic">Generic Porting Hints</a></font></h3>
1.10 espie 249: <ul>
250: <li><code>__OpenBSD__</code> should be used sparingly, if at all.
251: Constructs that look like
252: <pre>
253: #if defined(__NetBSD__) || defined(__FreeBSD__)
254: </pre>
255: are often inappropriate. Don't add blindly <code>__OpenBSD__</code>
256: to it. Instead, try to figure out what's going on, and what actual
257: feature is needed. Manual pages are often useful, as they include
258: historic comments, stating when a particular feature was incorporated
259: into BSD. Checking the numeric value of <code>BSD</code> against known
260: releases is often the right way. See
1.53 grunk 261: <a href="http://www.netbsd.org/Documentation/pkgsrc/">The NetBSD pkgsrc guide</a>
1.10 espie 262: for more information.
263: <li>Defining <code>BSD</code> is a bad idea. Try to include <code>sys/param.h</code>.
264: This not only defines <code>BSD</code>, it also gives it a proper value.
265: The right code fragment should look like:
266: <pre>
1.23 rohee 267: #if (defined(__unix__) || defined(unix)) && !defined(USG)
1.10 espie 268: #include <sys/param.h>
269: #endif
270: </pre>
271: <li>Test for features, not for specific OSes. In the long run, it is much
1.15 espie 272: better to test whether <code>tcgetattr</code> works than whether
273: you're running under BSD 4.3 or later, or SystemVR4. These kind of
274: tests just confuse the issue. The way to go about it is, for instance,
275: to test for one particular system, set up a slew of
276: <code>HAVE_TCGETATTR</code> defines, then proceed to the next system.
277: This technique separates features tests from specific OSes.
278: In a hurry, another porter can just add the whole set of
279: <code>-DHAVE_XXX</code> defines to the Makefile. One may also write
280: or add to a configure script to check for that feature and add it
281: automatically. As an example not to follow, check nethack 3.2.2
282: source: it assumes loads of things based on the system type. Most
283: of these assumptions are obsolete and no longer reflect reality:
284: POSIX functions are more useful than older BSD versus SystemV
285: differences, to the point that some traditional bsd functions are
1.10 espie 286: now only supported through compatibility libraries.
287:
288: <li>Avoid include files that include other includes that... First, because
1.15 espie 289: this is inefficient. Your project will end up including a file that
290: includes everything. Also, because it makes some problems difficult
291: to fix. It becomes harder to <em>not</em> include one particular file
292: at a given point.
1.10 espie 293:
294: <li>Avoid bizarre macro tricks. Undefining a macro that was defined by a
295: header file is a bad idea. Defining macros to get some specific behavior
1.15 espie 296: from an include file is also a bad idea: compilation modes should be
297: global. If you want POSIX behavior, say so, and
298: <code>#define POSIX_C_SOURCE</code>
1.10 espie 299: throughout the whole project, not when you feel like it.
300:
301: <li>Don't ever write system function prototypes. All modern systems,
302: OpenBSD included, have a standard location for these prototypes. Likely
1.15 espie 303: places include <code>unistd.h</code>, <code>fcntl.h</code> or
304: <code>termios.h</code>.
305: The man page frequently states where the prototype can be found.
306: You might need another slew of <code>HAVE_XXX</code> macros to
307: procure the right file. Don't worry about including the same file
308: twice, include files have guards that prevent all kinds of nastiness.<br>
1.10 espie 309: If some broken system needs you to write the prototype, don't impose
1.15 espie 310: on all other systems. Roll-your-own prototypes will break because they
311: may use types that are equivalent on your system, but are not portable
312: to other systems (<code>unsigned long</code> instead of
313: <code>size_t</code>), or get some <code>const</code> status wrong.
314: Also, some compilers, such as OpenBSD's own gcc,
1.10 espie 315: are able to do a better job with some very frequent functions such as
316: <code>strlen</code> if you include the right header file.
317:
1.58 ! sthen 318: <li>Carefully check the build log for any compiler warnings.
! 319: <ul><li>
! 320: <code>implicit declaration of function foo()</code>
! 321: indicates that a function prototype is missing.
! 322: This means that the compiler will assume the return type
! 323: to be an integer.
! 324: Where the function actually returns a pointer, on 64-bit
! 325: platforms it will be truncated, usually causing a segmentation
! 326: fault.
! 327: </ul>
! 328:
1.10 espie 329: <li>Don't use the name of a standard system function for anything else.
1.15 espie 330: If you want to write your own function, give it its own name, and
331: call that function everywhere. If you wish to revert to the
332: default system function, you just need to comment your code out,
333: and define your own name to the system function. Don't do it the
334: other way round. Code should look like this
1.10 espie 335: <pre>
336: /* prototype part */
337: #ifdef USE_OWN_GCVT
338: char *foo_gcvt(double number, size_t ndigit, char *buf);
339: #else
340: /* include correct file */
341: #include <stdlib.h>
342: /* use system function */
343: #define foo_gcvt gcvt
344: #endif
345:
346: /* definition part */
347: #ifdef USE_OWN_GCVT
348: char *foo_gcvt(double number, size_t ndigit, char *buf)
349: {
1.15 espie 350: /* proper definition */
351: }
1.10 espie 352:
353: /* typical use */
354: s = foo_gcvt(n, 15, b);
355: </pre>
1.1 marc 356: </ul>
1.35 naddy 357: <h3><font color="#0000e0"><a name="Other">Other Helpful Hints</a></font></h3>
1.1 marc 358: <ul>
1.15 espie 359: <li>Recent versions of <code>bsd.port.mk</code> set the installers
360: path. Specifically, they set <code>/usr/bin</code> and
361: <code>/bin</code> to be searched <em>before</em>
362: <code>/usr/local/bin</code> and <code>/usr/X11R6/bin</code>.
1.19 rohee 363: <li>Do <em>NOT</em> generate shared libraries if
1.49 espie 364: <code>${NO_SHARED_LIBS}</code> is set to yes (beware, it can be defined
1.21 rohee 365: only after inclusion of <code>bsd.port.mk</code>). If your port has
366: a GNU configure simply add the line
367: <code>CONFIGURE_ARGS += ${CONFIGURE_SHARED}</code> to the Makefile.
1.44 pvalchev 368: <li>It is OK to rely on a feature that appeared in a recent version of
369: <code>bsd.port.mk</code>, as people are supposed to update their
370: whole ports tree, including <code>bsd.port.mk</code>.
371: NEED_VERSION is now obsolete.
1.49 espie 372: <li>Prefer using <code>update-plist</code> to generate and update
373: packing-lists instead of doing things manually.
374: You can comment unwanted lines out.
375: <code>update-plist</code> can detect most file types and copy most
376: extra annotations correctly.
1.52 msf 377: <li>Add <code>USE_SYSTRACE=Yes</code> to <code>/etc/mk.conf</code> to
378: detect misbehaving scripts, makefiles, etc.
1.1 marc 379: <li>In OpenBSD <code>curses.h/libcurses/libtermlib</code> are the
380: ``new curses''. Change:<br>
1.15 espie 381: <code>ncurses.h ==> curses.h</code><br>
382: ``old (BSD) curses'' is available by defining
383: <code>_USE_OLD_CURSES_</code>
1.11 millert 384: before including <code>curses.h</code> (usually in a Makefile) and
1.15 espie 385: linking with <code>-locurses</code>.
1.11 millert 386: <li>In OpenBSD, terminal discipline has been upgraded from the older BSD
387: <code>sgtty</code> to the newer POSIX <code>tcgetattr</code> family.
1.15 espie 388: Avoid the older style in new code. Some code may define
389: <code>tcgetattr</code> to be a synonym for the older
390: <code>sgtty</code>, but this is at best a stopgap measure on OpenBSD.
391: The <code>xterm</code> source code is a very good example of
392: what not to do. Try to get your system functionality right: you
393: want a type that remembers the state of your terminal
394: (possible typedef), you want a function that extracts the current
395: state, and a function that sets the new state.
396: Functions that modify this state are more difficult, as they tend
397: to vary depending upon the system. Also, don't forget that you will
398: have to handle cases where you are not connected to a terminal,
399: and that you need to handle signals: not only termination, but
400: also background (<code>SIGTSTP</code>). You should always leave
401: the terminal in a sane state. Do your tests under an older shell,
402: such as sh, which does not reset the terminal in any way at
1.10 espie 403: program's termination.
1.15 espie 404: <li>The newer termcap/terminfo and curses, as included with OpenBSD,
405: include standard sequences for controlling color terminals. You
406: should use these if possible, reverting to standard ANSI color
407: sequences on other systems. However, some terminal descriptions
408: have not been updated yet, and you may need to be able to specify
409: these sequences manually. This is the way vim handles it. This is
410: not strictly necessary. Except for privileged programs, it is
411: generally possible to override a termcap definition through the
1.10 espie 412: <code>TERMCAP</code> variable and get it to work properly.
1.15 espie 413: <li>Signal semantics are tricky, and vary from one system to another.
414: Use <code>sigaction</code> to ensure a specific semantics, along
415: with other system calls referenced in the corresponding manpage.
1.1 marc 416: </ul>
417: <hr>
1.6 pauls 418: <a href="index.html"><img height=24 width=24 src=back.gif border=0 alt=OpenBSD></a>
1.20 rohee 419: <a href="mailto:www@openbsd.org">www@openbsd.org</a>
1.58 ! sthen 420: <br><small>$OpenBSD: porting.html,v 1.57 2007/06/18 15:27:16 espie Exp $</small>
1.1 marc 421: </body>
422: </html>
![[BACK]](/icons/back.gif){kind=icon}
Return to porting.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / www