Budowanie portów na OpenBSD

Najważniejszą rzeczą do zrobienia jest komunikacja. Zapytaj ludzi na ports@openbsd.org, czy ktoś nie pracuje już nad tym portem. Poinformuj o tym oryginalnego autora, włączając informacje, o problemach, które mogłeś znaleźć. Jeśli informacja o licencji wydaje się niewłaściwa, powiedz mu o tym. Jeśli musiałeś pokonywać złożone problemy, aby zbudować port, powiedz mu, co może poprawić. Jeśli są zainteresowani jedynie programowaniem na Linuksa i nie interesują się resztą świata Uniksa, postaraj się zmienić ich zdanie.

KOMUNIKACJA odróżnia udany port, od portu, który będzie wkrótce porzucony przez wszystkich.

Przede wszystkim, zapoznaj się z informacjami na temat portowania na tej stronie. Następnie zobacz dokumenty nawiązujące do tego tematu, zwłaszcza Listę rzeczy do sprawdzenia podczas portowania na OpenBSD.

Testuj, ponownie testuj, i jeszcze raz testuj!

Obecnie OpenBSD w pełni wspiera aktualizacje. Oznacza to, że kilka spraw musi zostać wykonanych w koncie.

Przedstaw port. Stwórz paczkę "gzipped tarball" katalogu portu. Możesz wtedy umieścić go na publicznym serwerze FTP lub HTTP, wysyłając adres paczki na ports@openbsd.org lub wysyłając ją w załączniku na ten sam adres. Wybierz metode, która Ci najbardziej odpowiada.

Spis dokumentacji portowania

• Dostępne informacje na temat portowania
• Polityka portowania na OpenBSD
• Zalecenia związane z bezpieczeństwem
• Ogólne wskazówki portowania
• Inne pomocne wskazówki

Dostępne informacje na temat portowania

• Lista rzeczy do sprawdzenia podczas portowania na OpenBSD.
• Wprowadzenie do aktualizacji portów w OpenBSD.
• Stronę podręcznika man bsd.port.mk(5). Dokumentuje ona infrastrukture makefile, która jest włączana na końcu każdego pojedyńczego pliku makefile portów. Wciąż istnieje kilka komentarzy na początku samego pliku, ale większość użytecznych informacji jest już udokumentowana.
• Nieliczne różnice w stosunku do systemów portów innych BSD, są w większości podsumowaniem różnic infrastruktur.
• Wykorzystanie bibliotek współdzielonych w portach na OpenBSD. Reguły, które istnieją, są niezwykle istotne, gdy używasz dzielonych bibliotek.
• Specyfika GNU autoconf, jak radzić sobie z nimą w kontekście portów OpenBSD.
• Pliki konfiguracyjne, jedna z trudności z na jakie natrafiają nowi developerzy, spowodowne wyjątkowymi narzędzia jakie porty OpenBSD wykorzystują do ich poprawnej obsługi.
• Przenoszenie oprogramowania audio do systemu OpenBSD.
• Dokumentacja Systemu pakietów NetBSD. Dokument ten opisuje wersje NetBSD systemu portów wprowadzonego przez FreeBSD, i jest bardzo pomocny.
• FreeBSD Porter's Handbook. Biblia portowania w FreeBSD.
• Lista mailingowa portów OpenBSD, ports@openbsd.org.

Polityka portowania na OpenBSD

• OpenBSD NIE używa /usr/local/etc/rc.d.
  /usr/local jest często współdzielone przez kilka maszyn poprzez NFS. Z tego powodu, pliki konfiguracyjne, które są specyficzne dla danej maszyny nie mogą być przechowywane w /usr/local, /etc jest centralnym repozytorium zależnych od indywidualnej maszyny plików konfiguracyjnych. Ponadto, zgodnie z polityką OpenBSD, pliki w /etc nie są nigdy uaktualniane automatycznie. Porty, które wymagają jakichś specyficznych ustawień do odpalenia powinny uprzedzić o tym administratora, aby wykonał je samodzielnie, zamiast ślepo instalować pliki.
• OpenBSD NIE kompresuje stron podręcznika man.
• OpenBSD NIE wymaga -lcrypt.
  Szyfrowanie DES jest częścią standardowego libc.
• OpenBSD posiada oddzielną przestrzeń nazw (ang. namespace) dla użytkowników i grup utworzonych przez porty. Więcej szczegółów w /usr/ports/infrastructure/db/user.list.
• OpenBSD jest mocno zaorientowane na bezpieczeństwo. Powinieneś przeczytać i zrozumieć sekcje bezpieczeństwa na tej stronie.
• Upewnij się o dodaniu taga CVS $OpenBSD$ do Makefile. Jeśli importujesz port z innego systemu, upewnij się o pozostawieniu także ich taga w Makefile.
• Celem jest uzyskanie wspierania portowanych aplikacji dla OpenBSD. Aby to osiągnąć, musisz przesłać wszystkie patch'e OpenBSD spowrotem do twórcy danej aplikacji.

Zalecenia związane z bezpieczeństwem

• Nie używaj kodu alpha lub beta podczas przygotowywania portu. Używaj najnowszego, regularnego lub zpatch'owanego, wydania.
• Każde oprogramowanie, które ma być zainstalowane jako serwer powinno być przeskanowane pod kątem przepełnień buforów (buffer overflows), zwłaszcza niebezpieczne jest używanie strcat/strcpy/strcmp/sprintf. Ogólnie, sprintf powinno być zastąpione przez snprintf.
• Nigdy nie używaj nazw plików zamiast prawdziwych zabezpieczeń. Istnieją liczne sytuacje wyścigów (race conditions), gdzie nie masz wystarczającej kontroli. Na przykład, atakujący, który ma już uprawnienia użytkownika na twoich maszynach może podmienić pliki w /tmp na symboliczne dowiązania dla bardziej znaczących plików, takich jak /etc/master.passwd.
• Dla przykładu, obie funkcje fopen i freopen tworzą nowy plik lub otwierają już istniejący do zapisu. Atakujący może utworzyć symboliczne dowiązanie z /etc/master.passwd do /tmp/addrpool_dump. W momencie, gdy go otworzysz, twój plik z hasłami jest wydany. Tak, nawet mimo unlink tuż przed operacją. Zmniejsza to jedynie nieco szanse. Używaj zamiast tego open z flagą O_CREAT|O_EXCL i fdopen.
• Innym, bardzo powszechnym problemem jest funkcja mktemp. Zwróć uwagę na ostrzeżenia konsolidatora (linker) bsd, na temat jej użycia. Musi to być naprawione. Nie jest to kwestia jedynie s/mktemp/mkstemp/g.
  Więcej informacji znajdziesz na stronie manuala mktemp(3). Popraw kod używając mkstemp, dotyczy to źródeł między innymi ed czy mail. Rzadkim wypadkiem jest kod prawidłowo korzystający z mktemp; można spotkać się z tym w porcie rsync.
• Sama możliwość czytania (read) nie oznacza, że powinieneś ją wykorzystywać. Dobrze znaną dziurą tej natury jest problem z startx. Jako program uprzywilejowany (setuid), mógłbyś wywołać startx z jakimkolwiek plikiem, jako skryptem. Jeśli plik ten nie był poprawnym plikiem skryptu powłoki, wypisany zostałby komunikat o błędzie składni razem z pierwszą linią niepoprawnego pliku i bez jakichkolwiek dalszych sprawdzeń uprawnień. Dość poręczne, aby pobrać pierwszą linie zaszyfrowanego pliku haseł, a który często zaczyna się od wpisu dla użytkownika root. Nie otwieraj swojego pliku, a następnie używaj fstat na otwartym deskryptorze, aby sprawdzić, czy rzeczywiście powinieneś być zdolnym do jego otwarcia (albo atakujący przy pomocy /dev/rst0 przewinie go) -- otwieraj go tylko dla właściwych uid/gid/zestawów grup.
• Nie używaj niczego, co tworzy kopie powłoki (forks a shell) w programach uprzywilejowanych (setuid), przed zrzuceniem uprawnień. Dotyczy to m.in popen i system. Używaj zamiast tego fork, pipe i execve.
• Przekazuj do innych plików otwarte deskryptory, zamiast nazw plików, aby uniknąć sytuacji wyścigów. Nawet, jeśli jakiś program nie przyjmuje deskryptorów, wciąż możesz użyć /dev/fd/0.
• Prawa dostępu są związane z deskryptorem pliku. Gdy potrzebujesz praw użytkownika uprzywilejowanego (setuid) do otwarcia pliku, otwórz go, a następnie zrzuć uprawnienia. Nadal będziesz miał dostęp do tego otwartego deskryptora, ale będziesz już miał mniej powodów do zmartwień. Ma to jednak i drugą stronę: nawet po zrzuceniu uprawnień, wciąż powinieneś uważać na te deskryptory.
• Unikaj programów uprzywilejowanych (root setuid) jak tylko możesz. W skrócie, użytkownik root może wszystko, ale uprawnienia root'a są bardzo rzadko niezbędne, może poza tworzeniem gniazd na portach o numerach niższych niż 1024. Jest kwestią sporną, czy nie lepiej jest uruchamiać takie programy sieciowe pod kontrolą inetd i po prostu dodać odpowiednie wpisy w inetd.conf. Musisz znać sztukę pisania demonów (daemons), aby to osiągnąć w inny sposób. Można powiedzieć, że nie powinieneś pisać programów uprzywilejowanych (setuid), jeśli nie wiesz jak to robić.
• Używaj setgid zamiast setuid. Poza specyficznymi plikami wymaganymi przez programy z setgid, większość plików nie ma praw do zapisu przez grupę. Stąd, problemy z bezpieczeństwem w programach z setgid nie będą stanowiły takiego zagrożenia dla systemu: z uprawnieniami jedynie grupy, w najgorszym przypadku intruz będzie mógł zmienić punktacje w jakiejś grze lub tym podobne. Zobacz port xkobo dla przykładu takiej zmiany.
• Nie ufaj plikom z prawami zapisu przez grupę. Nawet, jeśli są one szczegółowo analizowane (audited), programy z setgid nie są jednak postrzegane jako istotne potencjalne źródło dziur w zabezpieczeniach. Stąd rzeczy, które mogą naruszać, nie powinny być uznawane za wrażliwe informacje.
• Nie ufaj swojemu środowisku systemowemu! Dotyczy to prostych rzeczy, takich jak twoja ścieżka PATH (nigdy nie używaj system z nie pełną ścieżką, unikaj execvp), ale i bardziej subtelnych rzeczy jak twoje locale, timezone, termcap, i tak dalej. Wystrzegaj się pośredniości: nawet, jeśli rozważasz wszystkie założenia, programy wywoływane bezpośrednio nie muszą tego koniecznie wymagać. Nigdy nie używaj funkcji system w uprzywilejowanych programach, zbuduj swoją linię poleceń, kontrolowane środowisko pracy, i wywołaj bezpośrednio execve. Strona podręcznika man perlsec jest dobrym przewodnikiem na temat takich problemów.
• Nigdy nie używaj skryptów powłoki z setuid. Charakteryzują się one brakiem odpowiedniego bezpieczeństwa. Opakuj je w jakiś kod C zapewniający właściwe środowisko systemowe. Z drugiej strony, OpenBSD dostarcza możliwości wykorzystywania bezpiecznych skryptów perl.
• Uwaga na program dynamicznego ładowania (the dynamic loader). Jeśli uruchamiasz program setuid, będzie one używał jedynie zaufanych bibliotek, które były przeskanowane przez ldconfig. Setgid to za mało.
• Dynamiczne biblioteki są zawiłe. Kod C++ powoduje podobne problemy. Przede wszystkim, biblioteki mogą podejmować pewne decyzje na podstawie twoich ustawień środowiska systemowego nawet jeszcze zanim zostanie sprawdzony status setuid. Z punktu widzenia twórcy bibliotek problem ten dotyczy issetugid w OpenBSD. Nie próbuj przenosić (to port) bibliotek, jeśli nie rozumiesz całkowicie natury problemu.

Ogólne wskazówki portowania

• __OpenBSD__ powinno być używane oszczędnie, jeśli w ogóle. Konstrukcje, które wyglądają jak ta

              #if defined(__NetBSD__) || defined(__FreeBSD__)
         

  są często niewłaściwe. Nie dodawaj na ślepo __OpenBSD__ do nich. Zamiast tego, postaraj się zrozumieć co się dzieje i jaka właściwie funkcja jest wymagana. Strony podręcznika man są często pomocne, ponieważ zawierają wiele historycznych komentarzy, łącznie z informacją, kiedy konkretna funkcja została wprowadzona w BSD. Porównywanie numerycznej wartości BSD ze znanymi wydaniami jest często właściwą drogą. Zobacz przewodnik do NetBSD pkgsrc w celu uzyskania większej ilości informacji.
• Definiowanie BSD jest złym pomysłem. Postaraj się dołączyć sys/param.h. Definiuje on nie tylko BSD, ale i nadaje mu właściwą wartość. Właściwy fragment kody powinien powinien wyglądać jak:

             #if (defined(__unix__) || defined(unix)) && !defined(USG)
             #include <sys/param.h>
             #endif
         

• Testuj pod kątem funkcji, nie specyficznych systemów operacyjnych. Na dłuższą metę, jest dużo lepiej sprawdzać, czy tcgetattr po prostu działa, bez rozróżnienia, czy jest ona wywoływana na BSD 4.3 lub późniejszym, czy SystemVR4. Tego typu testy wprowadzają tylko wątpliwości. Właściwą drogą jest natomiast sprawdzanie, czy konkretny system definiuje HAVE_TCGETATTR, a następnie przejście do następnego systemu. Technika ta oddziela testowanie funkcji dla specyficznego systemu operacyjnego. W pośpiechu, inna osoba portująca może po prostu dodać cały zestaw definicji -DHAVE_XXX do pliku Makefile. Można także napisać lub dodać skrypt "configure", aby sprawdzać tą funkcje i dodawać ją automatycznie. Jako negatywny przykład przeglądnij źródła nethack 3.2.2: zakłada się tam ładowanie rzeczy na podstawie typu systemu operacyjnego. Większość tych założeń jest przestarzała i nie odzwierciedla rzeczywistości: funkcje POSIX są bardziej przydatne niż stare BSD vs. SystemV rozróżnienia, albowiem obecnie niektóre tradycyjne funkcje bsd są wspierane jedynie poprzez biblioteki kompatybilności.
• Unikaj dołączania (include) plików, które dołączają inne pliki, które... Przede wszystkim ponieważ jest to niewydajne. Twój projekt ostatecznie skończy załączając plik, który załącza wszystko. A także, ponieważ powoduje to, że pewne problemy są trudne do naprawienia. Trudniejsze staje się nie załączanie pojedynczego pliku w danym punkcie.
• Unikaj dziwnych trików z makrami. Oddefiniowywanie (undefining) makra, które było zdefiniowane przez plik nagłówkowy jest złym pomysłem. Definiowanie makra, aby uzyskać konkretne zachowanie się plików nagłówkowych jest także złym pomysłem: tryby kompilacji powinny być globalne. Powiedzmy, że pożądasz zachowania POSIX załączanego pliku nagłówkowego, więc definiujesz #define POSIX_C_SOURCE w całym projekcie, a nie kiedy ci się podoba.
• Nigdy nie pisz prototypów funkcji systemowych. Wszystkie nowoczesne systemy, włączając OpenBSD, mają standardowe lokalizacje dla tych prototypów. Zwykle są to unistd.h, fcntl.h lub termios.h. Odpowiednia strona podręcznika systemowego man określa, gdzie dany prototyp może być odnaleziony. Możesz potrzebować kolejnych makr HAVE_XXX, aby otrzymać właściwy plik. Nie martw się włączaniem tego samego pliku dwukrotnie, pliki nagłówkowe mają blokady zapobiegające takim wypadkom.
  Jeśli jakiś niepoprawny system wymaga od ciebie napisania prototypu, nie narzucaj tego na wszystkich pozostałych systemach. Twoje własne prototypy będą sprawiały problem, ponieważ mogą używać typów, które są poprawne na twoim systemie, ale nie są poprawne na innych (unsigned long zamiast size_t), lub mają jakiś zły status const. Poza tym, niektóre kompilatory, jak własne gcc OpenBSD, mogą znacznie lepiej wykonywać swoją prace na wielu często spotykanych funkcjach, jak np strlen, jeśli załączysz odpowiednie pliki nagłówkowe.
• Nie używaj nazw standardowych funkcji systemowej do niczego innego. Jeśli chcesz napisać swoją własną funkcje, nadaj jej własną nazwę i używaj jej wszędzie. Jeśli będziesz chciał powrócić do domyślnej funkcji systemowej, po prostu wstaw kod do komentarzy, i podaj własną nazwę funkcji systemowej. Nie rób tego w inny sposób. Kod powinien wyglądać w następujący sposób:

         /* czesc prototypowa */
         #ifdef USE_OWN_GCVT
         char *foo_gcvt(double number, size_t ndigit, char *buf);
         #else
         /* zalacz odpowiedni plik */
         #include <stdlib.h>
         /* uzyj funkcji systemowej */
         #define foo_gcvt  gcvt
         #endif
  
         /* czesc definiujaca */
         #ifdef USE_OWN_GCVT
         char *foo_gcvt(double number, size_t ndigit, char *buf)
            {
            /* wlasciwa definicja */
            }
  
         /* typowe uzycie */
         s = foo_gcvt(n, 15, b);
         

Inne pomocne wskazówki

• Najnowsze wersje bsd.port.mk ustalają ścieżki (path) instalacji. Zwłaszcza ustalają, że /usr/bin i /bin są przeszukiwane przed /usr/local/bin i /usr/X11R6/bin.
• NIE generuj bibliotek współdzielonych, jeśli ${NO_SHARED_LIBS} ma wartość 'yes' (uwaga, może to być zdefiniowane jedynie po załączeniu bsd.port.mk). Jeśli twój port ma GNU configure, po prostu dodaj linie CONFIGURE_ARGS += ${CONFIGURE_SHARED} do pliku Makefile.
• W porządku jest opierać się na funkcjach, które pojawiły się najnowszych wersjach bsd.port.mk, albowiem użytkownicy powinni uaktualniać całe swoje drzewo portów, włączając bsd.port.mk. NEED_VERSION jest obecnie przeżytkiem.
• Preferuj update-plist przy generacji i aktualizacji list zawartości paczki zamiast wykonywać te czynności ręcznie. Możesz zakomentować niechciane linie. update-plist potrafi wykryć większość typów plików oraz dołączyć dodatkowe wpisy poprawnie.
• Dodaj USE_SYSTRACE=Yes na końcu /etc/mk.conf aby bezpośrednio zmienić zachowanie skryptów, plików makefiles, itp.
• W OpenBSD curses.h/libcurses/libtermlib są ``nowym curses''. Zmień:
  ncurses.h ==> curses.h
  ``stare (BSD) curses'' jest dostępne poprzez zdefiniowanie _USE_OLD_CURSES_ przed załączeniem curses.h (zwykle w pliku Makefile) oraz konsolidowaniu (linking) z -locurses.
• W OpenBSD, dyscyplina terminali została zaktualizowana z starszej BSD sgtty do nowszej (POSIX) rodziny tcgetattr. Unikaj starego stylu w nowym kodzie. Część kodów może definiować tcgetattr jako synonim starszego sgtty, lecz jest to w najlepszym wypadku prowizorka na OpenBSD. Kod źródłowy xterm jest dobrym przykładem, czego nie należy robić. Postaraj się uzyskać funkcjonalność systemu poprawnie: chcesz typu, który zapamiętuje stan twojego terminala (dopuszczalne typedef), chcesz funkcji, która przywraca zapamiętany stan, oraz funkcje, która ustawia nowy stan. Funkcje, które modyfikują ten stan są trudniejsze, albowiem mają skłonność do zróżnicowania w zależności od systemu. Poza tym, nie zapominaj, że będziesz musiał poradzić sobie z przypadkami, kiedy nie jesteś podłączony do terminala, oraz o przechwytywaniu sygnałów (to handle signals): nie tylko zakończenia, ale także przejścia w tło (SIGTSTP). Powinieneś zawsze przywracać terminal do pierwotnego stanu. Przeprowadź testy na starej powłoce, jak sh, która nie resetuje w żaden sposób terminala po zakończeniu pracy programu.
• Nowszy termcap/terminfo i curses, wykorzystywane w OpenBSD, zawierają standardowe sekwencje dla kontrolowania kolorowych terminali. Powinieneś ich używać, jeśli to tylko możliwe, odzwierciadlając standardowe sekwencje kolorów z innych systemów. Jednakże, niektóre opracowania nie zostały jeszcze zaktualizowane, lecz powinieneś być w stanie zdefiniować te sekwencje ręcznie. W taki sposób robi to vim. Nie jest to bezwzględnie niezbędne. Poza programami uprzywilejowanymi, jest ogólnie możliwe nadpisanie (override) definicji termcap'a poprzez zmienną TERMCAP i uzyskać pożądane działanie.
• Sematyka sygnałów jest zdradliwa, i różni się pomiędzy poszczególnymi systemami. Używaj sigaction aby zapewnić specyficzną sematykę, razem z pozostałymi wywołaniami systemowymi (system calls) opisanymi w odpowiednich stronach podręcznika man.