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