Building an OpenBSD port

=================================================================== RCS file: /cvsrepo/anoncvs/cvs/www/Attic/porting.html,v retrieving revision 1.59 retrieving revision 1.60 diff -u -r1.59 -r1.60 --- www/Attic/porting.html 2011/01/17 16:28:24 1.59 +++ www/Attic/porting.html 2013/12/11 12:09:27 1.60 @@ -1,422 +1,29 @@ - + + - - - - - - Building an OpenBSD port + + + OpenBSD Porter's Handbook

Building an OpenBSD port

- - So you've just compiled your favorite software package on your - OpenBSD machine and you want to share your effort by turning - it into a standard port. What to do?

- The most important thing to do is to communicate. - Ask people on ports@openbsd.org - if they are working on the same port. Tell the original software - author about it, including problems you may find. If licensing - information appears incorrect tell him. If you had to jump through - loops to make the port build, tell him what he can fix. If they are - only developing on Linux and feel like ignoring the rest of the Unix - world, try to make them change their view. -

- COMMUNICATION makes the difference between a successful - port and a port that will slowly be abandoned by everyone. -

- First look at the porting information on this page. Then check - out the referenced documents, especially the OpenBSD porting - checklist. -

- Test, then re-test, and finally test again! -

- OpenBSD now fully supports updates. This means that - quite a few issues - must be taken into account. -

- Submit the port. Create a gzipped tarball of the port directory. - You can then either place it on a public FTP or HTTP server, sending - its address to ports@openbsd.org - or send the port mime encoded to the same address. Pick whichever - method works best for you. -

- Porting some new software takes time. Maintaining it over time is harder. - It is quite okay to port software, and let other people handle it - afterwards. It is also okay to help other people update and maintain - other ports, as long as you communicate to avoid doing the same things - twice. -

- In the OpenBSD culture, MAINTAINERship is not a status item, - but a responsibility. We have CVS and comments to give credit to the - person who did the work. A port MAINTAINER is something else: - a person who assumes responsibility for the working of the port, and is - willing to spend some time ensuring it works as best as can be. + If you are not redirected automatically, follow the link + to http://www.openbsd.org/faq/ports -

- -

Available Porting Information

OpenBSD porting checklist. -
OpenBSD ports update guidelines. -
The man page - bsd.port.mk(5). - This documents the ports infrastructure makefile that is - included at the end of each individual port makefile. - There are still a few comments at the start of - the file itself, but most of the useful information is now - documented. -
Some differences from other BSD port systems, mostly a summary - of infrastructure differences. -
Using shared libraries - in OpenBSD Ports. The rules there are very - important as soon as you use shared libraries. -
GNU autoconf specificities, - how to deal with it in the context of OpenBSD ports. -
Configuration files, - one frequent stumbling block for new developers, and the unique - tools the OpenBSD ports tree has to deal with these. -
Porting audio applications to OpenBSD. -
The - - NetBSD Package System documentation. This document describes - NetBSD's version of the FreeBSD ports system and is quite helpful. -
The - FreeBSD - Porter's Handbook. This is the FreeBSD porting bible. -
The OpenBSD ports mailing list, - ports@openbsd.org. -

OpenBSD Porting Policy

OpenBSD does NOT use /usr/local/etc/rc.d.
- /usr/local is often shared between several machines - thanks to NFS. For this reason, configuration files that are specific - to a given machine can't be stored under /usr/local, - /etc is the central repository for per machine - configuration files. Moreover, OpenBSD policy is to never update - files under /etc automatically. Ports that need some - specific boot setup should advise the administrator about what to do - instead of blindly installing files. -
OpenBSD does NOT compress man pages. -
OpenBSD does NOT require -lcrypt.
- DES encryption is part of the standard libc. -
OpenBSD has a separate namespace for users and groups created by ports. - See /usr/ports/infrastructure/db/user.list for details. -
OpenBSD is strongly security-oriented. You should read and understand - this page's security section. -
Be sure to add the $OpenBSD$ CVS tag to - the Makefile. If importing a port from another system be sure to - leave their tag in the Makefile, too. -
The goal is to get all ported applications to support OpenBSD. To - achieve this goal you must feed any OpenBSD patches - back to the application maintainer. -

Security Recommendations

- There are many security problems to worry about. If - you are not absolutely sure of what you are doing please request - help from the ports mailing - list. - -

Do not use alpha or beta code when preparing a port. Use the - latest regular or patch release. - -
Any software to be installed as a server should be scanned - for buffer overflows, especially unsafe use of - strcat/strcpy/strcmp/sprintf. In general, - sprintf should be replaced with snprintf. - -
Never use filenames instead of true security. There are numerous race - conditions where you don't have proper control. For instance, an attacker - who already has user privileges on your machines may replace files in - /tmp with symbolic links to more strategic files, such as - /etc/master.passwd. - -
For instance, both fopen and freopen - create a new file or open an existing file for - writing. An attacker may create a symbolic link from - /etc/master.passwd to /tmp/addrpool_dump. The - instant you open it, your password file is hosed. Yes, even with - an unlink right before. You only narrow the window - of opportunity. Use open with - O_CREAT|O_EXCL and fdopen instead. - -
Another very common problem is the mktemp - function. Heed the warnings of the bsd linker about its uses. - These must be fixed. - This is not quite as simple as s/mktemp/mkstemp/g.
- Refer to - mktemp(3) for more information. - Correct code using mkstemp includes the source to - ed or mail. - A rare instance of code that uses mktemp correctly - can be found in the rsync port. - -
Just because you can read it doesn't mean you should. A well-known hole - of this nature was the startx problem. As a setuid program, - you could launch startx with any file as a script. If the file was not - a valid shell script, a syntax error message would follow, along with the - first line of the offending file, without any further permission check. - Pretty handy to grab the first line of a shadow passwd file, considering - these often start with root entry. Do not open your file, and then do - an fstat on the open descriptor to check if you should have - been able to open it (or the attacker will play with /dev/rst0 and rewind - your tape) -- open it with the correct uid/gid/grouplist set. - -
Don't use anything that forks a shell in setuid programs before dropping - your privileges. This includes popen and - system. - Use fork, pipe and execve instead. - -
Pass open descriptors instead of filenames to other programs to - avoid race conditions. Even if a program does not accept file - descriptors, you can still use /dev/fd/0. - -
Access rights are attached to file descriptors. If you need setuid rights - to open a file, open that file, then drop your privileges. You can still - access the open descriptor, but you have less to worry about. This is - double-edged: even after dropping privileges, you should still watch out - for those descriptors. - -
Avoid root setuid as much as you can. Basically, root can do anything, - but root rights are very rarely needed, except maybe to create - socket ports with a number under 1024. It is arguably better to - keep that under inetd - control and just add the relevant entries to inetd.conf. - You must know the appropriate magic for writing daemons to achieve that. - It could be argued that you have no business writing setuid programs - if you don't know how to do that. - -
Use setgid instead of setuid. Apart from those specific files needed - by setgid programs, most files are not group-writable. Hence, a - security problem in a setgid program won't compromise your system as - much: with only group rights, the worst an intruder will be able to - do is hack a games score table or some such. - See the xkobo port for an instance of such a change. - -
Don't trust group-writable files. Even though they are audited, - setgid programs are not perceived as important potential security - holes. Hence stuff they can tamper with shouldn't be considered - sensitive information. - -
Don't trust your environment ! This involves simple things such as - your PATH (never use system with an - unqualified name, avoid execvp), but also more subtle - items such as your locale, timezone, termcap, and so on. - Be aware of transitivity: even though you're taking full precautions, - programs you call directly won't necessarily. Never - use system in privileged programs, build your command - line, a controlled environment, and call execve directly. - The perlsec man page is a good tutorial on such problems. - -
Never use setuid shell-scripts. These are inherently insecure. - Wrap them into some C code that ensures a proper environment. - On the other hand, OpenBSD features secure perl scripts. - -
Beware the dynamic loader. If you are running setuid, it will only - use trusted libraries that were scanned with ldconfig. - Setgid is not enough. - -
Dynamic libraries are tricky. C++ code sets a similar problem. - Basically, libraries may take some action based upon your environment - before your main program even gets to check its setuid status. - OpenBSD issetugid addresses this problem, from the - library writer point of view. Don't try to port libraries unless you - understand this issue thoroughly. -

Generic Porting Hints

__OpenBSD__ should be used sparingly, if at all. - Constructs that look like -
```
-            #if defined(__NetBSD__) || defined(__FreeBSD__)
-       
```
- are often inappropriate. Don't add blindly __OpenBSD__ - to it. Instead, try to figure out what's going on, and what actual - feature is needed. Manual pages are often useful, as they include - historic comments, stating when a particular feature was incorporated - into BSD. Checking the numeric value of BSD against known - releases is often the right way. See - The NetBSD pkgsrc guide - for more information. -
Defining BSD is a bad idea. Try to include sys/param.h. - This not only defines BSD, it also gives it a proper value. - The right code fragment should look like: -
```
-           #if (defined(__unix__) || defined(unix)) && !defined(USG)
-           #include <sys/param.h>
-           #endif
-       
```
-
Test for features, not for specific OSes. In the long run, it is much - better to test whether tcgetattr works than whether - you're running under BSD 4.3 or later, or SystemVR4. These kind of - tests just confuse the issue. The way to go about it is, for instance, - to test for one particular system, set up a slew of - HAVE_TCGETATTR defines, then proceed to the next system. - This technique separates features tests from specific OSes. - In a hurry, another porter can just add the whole set of - -DHAVE_XXX defines to the Makefile. One may also write - or add to a configure script to check for that feature and add it - automatically. As an example not to follow, check nethack 3.2.2 - source: it assumes loads of things based on the system type. Most - of these assumptions are obsolete and no longer reflect reality: - POSIX functions are more useful than older BSD versus SystemV - differences, to the point that some traditional bsd functions are - now only supported through compatibility libraries. - -
Avoid include files that include other includes that... First, because - this is inefficient. Your project will end up including a file that - includes everything. Also, because it makes some problems difficult - to fix. It becomes harder to not include one particular file - at a given point. - -
Avoid bizarre macro tricks. Undefining a macro that was defined by a - header file is a bad idea. Defining macros to get some specific behavior - from an include file is also a bad idea: compilation modes should be - global. If you want POSIX behavior, say so, and - #define POSIX_C_SOURCE - throughout the whole project, not when you feel like it. - -
Don't ever write system function prototypes. All modern systems, - OpenBSD included, have a standard location for these prototypes. Likely - places include unistd.h, fcntl.h or - termios.h. - The man page frequently states where the prototype can be found. - You might need another slew of HAVE_XXX macros to - procure the right file. Don't worry about including the same file - twice, include files have guards that prevent all kinds of nastiness.
- If some broken system needs you to write the prototype, don't impose - on all other systems. Roll-your-own prototypes will break because they - may use types that are equivalent on your system, but are not portable - to other systems (unsigned long instead of - size_t), or get some const status wrong. - Also, some compilers, such as OpenBSD's own gcc, - are able to do a better job with some very frequent functions such as - strlen if you include the right header file. - -
Carefully check the build log for any compiler warnings. -
- - implicit declaration of function foo() - indicates that a function prototype is missing. - This means that the compiler will assume the return type - to be an integer. - Where the function actually returns a pointer, on 64-bit - platforms it will be truncated, usually causing a segmentation - fault. -
- -

Don't use the name of a standard system function for anything else. - If you want to write your own function, give it its own name, and - call that function everywhere. If you wish to revert to the - default system function, you just need to comment your code out, - and define your own name to the system function. Don't do it the - other way round. Code should look like this -

-       /* prototype part */
-       #ifdef USE_OWN_GCVT
-       char *foo_gcvt(double number, size_t ndigit, char *buf);
-       #else
-       /* include correct file */
-       #include <stdlib.h>
-       /* use system function */
-       #define foo_gcvt  gcvt
-       #endif
-
-       /* definition part */
-       #ifdef USE_OWN_GCVT
-       char *foo_gcvt(double number, size_t ndigit, char *buf)
-          {
-          /* proper definition */
-          }
-
-       /* typical use */
-       s = foo_gcvt(n, 15, b);
-

Other Helpful Hints

Recent versions of bsd.port.mk set the installers - path. Specifically, they set /usr/bin and - /bin to be searched before - /usr/local/bin and /usr/X11R6/bin. -
Do NOT generate shared libraries if - ${NO_SHARED_LIBS} is set to yes (beware, it can be defined - only after inclusion of bsd.port.mk). If your port has - a GNU configure simply add the line - CONFIGURE_ARGS += ${CONFIGURE_SHARED} to the Makefile. -
It is OK to rely on a feature that appeared in a recent version of - bsd.port.mk, as people are supposed to update their - whole ports tree, including bsd.port.mk. - NEED_VERSION is now obsolete. -
Prefer using update-plist to generate and update - packing-lists instead of doing things manually. - You can comment unwanted lines out. - update-plist can detect most file types and copy most - extra annotations correctly. -
Add USE_SYSTRACE=Yes to /etc/mk.conf to - detect misbehaving scripts, makefiles, etc. -
In OpenBSD curses.h/libcurses/libtermlib are the - ``new curses''. Change:
- ncurses.h ==> curses.h
- ``old (BSD) curses'' is available by defining - _USE_OLD_CURSES_ - before including curses.h (usually in a Makefile) and - linking with -locurses. -
In OpenBSD, terminal discipline has been upgraded from the older BSD - sgtty to the newer POSIX tcgetattr family. - Avoid the older style in new code. Some code may define - tcgetattr to be a synonym for the older - sgtty, but this is at best a stopgap measure on OpenBSD. - The xterm source code is a very good example of - what not to do. Try to get your system functionality right: you - want a type that remembers the state of your terminal - (possible typedef), you want a function that extracts the current - state, and a function that sets the new state. - Functions that modify this state are more difficult, as they tend - to vary depending upon the system. Also, don't forget that you will - have to handle cases where you are not connected to a terminal, - and that you need to handle signals: not only termination, but - also background (SIGTSTP). You should always leave - the terminal in a sane state. Do your tests under an older shell, - such as sh, which does not reset the terminal in any way at - program's termination. -
The newer termcap/terminfo and curses, as included with OpenBSD, - include standard sequences for controlling color terminals. You - should use these if possible, reverting to standard ANSI color - sequences on other systems. However, some terminal descriptions - have not been updated yet, and you may need to be able to specify - these sequences manually. This is the way vim handles it. This is - not strictly necessary. Except for privileged programs, it is - generally possible to override a termcap definition through the - TERMCAP variable and get it to work properly. -
Signal semantics are tricky, and vary from one system to another. - Use sigaction to ensure a specific semantics, along - with other system calls referenced in the corresponding manpage. -

www@openbsd.org -
$OpenBSD: porting.html,v 1.59 2011/01/17 16:28:24 jasper Exp $ +
$OpenBSD: porting.html,v 1.60 2013/12/11 12:09:27 sthen Exp $