{"id":13507959,"url":"https://github.com/nieklinnenbank/FreeNOS","last_synced_at":"2025-03-30T09:33:14.742Z","repository":{"id":28889394,"uuid":"32414048","full_name":"nieklinnenbank/FreeNOS","owner":"nieklinnenbank","description":"FreeNOS (Free Niek's Operating System) is an experimental microkernel based operating system for learning purposes written in C++. You may use the code as you wish under the terms of the GPLv3.","archived":false,"fork":false,"pushed_at":"2021-03-23T11:42:36.000Z","size":4912,"stargazers_count":870,"open_issues_count":9,"forks_count":1337,"subscribers_count":78,"default_branch":"master","last_synced_at":"2025-03-25T00:33:50.234Z","etag":null,"topics":["arm","c-plus-plus","intel","microkernel","operating-system","raspberry-pi","raspberrypi"],"latest_commit_sha":null,"homepage":"http://www.FreeNOS.org","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nieklinnenbank.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-17T19:03:38.000Z","updated_at":"2025-03-06T15:57:00.000Z","dependencies_parsed_at":"2022-07-12T16:09:22.079Z","dependency_job_id":null,"html_url":"https://github.com/nieklinnenbank/FreeNOS","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nieklinnenbank%2FFreeNOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nieklinnenbank%2FFreeNOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nieklinnenbank%2FFreeNOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nieklinnenbank%2FFreeNOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nieklinnenbank","download_url":"https://codeload.github.com/nieklinnenbank/FreeNOS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245965849,"owners_count":20701738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arm","c-plus-plus","intel","microkernel","operating-system","raspberry-pi","raspberrypi"],"created_at":"2024-08-01T02:00:44.225Z","updated_at":"2025-03-30T09:33:14.255Z","avatar_url":"https://github.com/nieklinnenbank.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"About {#mainpage}\n=====\n\nFreeNOS (Free Niek's Operating System) is an experimental microkernel based\noperating system for learning purposes written in C++. You may use the code\nas you wish under the terms of the GPLv3.\n\nVisit the project website at http://www.FreeNOS.org for more information.\n\nFeatures\n========\n\n* Intel x86 (PC) and ARMv6/ARMv7 architectures (Raspberry Pi 1,2,3, Allwinner H2+/H3)\n* Virtual memory\n* Simple task scheduling\n* Inter Process Communication (IPC)\n* Symmetric Multi Processing with MPI support (via console and ethernet)\n* Devices:\n    * VGA/Keyboard consoles (also supported by Ed's libteken http://80386.nl/projects/libteken/)\n    * i8250 serial UART\n    * PCI host controller\n    * CMOS RTC clock\n    * ATA host controller\n    * Allwinner H2+/H3 ethernet controller\n    * Loopback ethernet controller\n* Filesystems:\n    * Virtual file system (VFS)\n    * Temporary file system (TmpFS)\n    * Linnenbank file system (LinnFS)\n* Networking (IP, UDP, ICMP, ARP)\n* POSIX, ANSI C libraries\n* Dynamic and Shared memory\n* Fully automatic autotester\n* Automated continuous integration using jenkins (http://www.jenkins.io) and Vagrant (http://www.vagrantup.com)\n* All sources documented with Doxygen (http://www.doxygen.org/)\n* User and kernel code written from scratch in C++\n* Very small microkernel (~2K lines of C++ code including a tiny part in assembly)\n* Builds with recent GCC (http://gcc.gnu.org/), LLVM (http://www.llvm.org/) and SCons (http://www.scons.org/) versions on POSIX systems\n\nHost Setup\n==========\n\nFirst install all required build dependencies. FreeNOS needs SCons, an C++ compiler and\nfor Intel targets a tool to generate ISO images. Follow the instructions below to install\nthe build dependencies on your host OS.\n\n*Ubuntu*\n\nUpdate your system repository cache and install the required development tools using:\n\n    $ sudo apt-get update\n    $ sudo apt-get install build-essential scons genisoimage xorriso qemu-system binutils-multiarch u-boot-tools liblz4-tool\n\nIf your Ubuntu host is 64-bit, you need to install the GCC multilib package\nto cross compile for the 32-bit architecture:\n\n    $ sudo apt-get install gcc-multilib g++-multilib\n\nAlternatively, you can install the LLVM/Clang compiler as well:\n\n    $ sudo apt-get install clang\n\n*FreeBSD*\n\nUpdate your system repository cache and install the required development tools using:\n\n    % su -\n    # pkg update\n    # pkg install qemu scons cdrkit-genisoimage xorriso gcc u-boot-tools liblz4\n\nOn FreeBSD, make sure that the latest version of the GNU linker (from pkg) is used:\n\n    # mv /usr/bin/ld.bfd /usr/bin/ld.bfd.orig\n\nBuilding FreeNOS\n================\n\nTo download and extract the released source code on your host OS, run the\nfollowing commands. Replace 'x.x.x' with the version of FreeNOS:\n\n    $ wget http://www.FreeNOS.org/pub/FreeNOS/source/FreeNOS-x.x.x.tar.gz\n    $ tar zxf FreeNOS-x.x.x.tar.gz\n\nTo get the latest development source, you can clone the GIT archive:\n\n    $ git clone https://github.com/nieklinnenbank/FreeNOS\n\nTo build FreeNOS using default settings (Intel, using GCC with debugging enabled), run:\n\n    $ scons\n\nTo build FreeNOS with all full build commands printed on the console, set the\nVERBOSE build variable to True:\n\n    $ scons VERBOSE=True\n\nTo build FreeNOS with compiler optimizations enabled, set DEBUG to False.\nNote that will make debugging using GDB more difficult:\n\n    $ scons DEBUG=False\n\nInstead of providing build variables on the command line, you can\nalso change the 'build.conf' configuration file for the target. The build configuration\nfile contains build variables, such as compiler flags and parameters for the target.\nSimilary, the 'build.host.conf' file contains build variables for the host OS programs.\nSee the example build.conf and build.host.conf files for more details.\n\nAdditionally, any environment variables set in the shell will be automatically converted\nto identical build variables when running scons.\n\nTo build for the Raspberry Pi 2, copy the example build configuration file and run SCons:\n\n    $ cp config/arm/raspberry2/build.conf .\n    $ scons\n\nTo cleanup your build directory, use:\n\n    $ scons -c\n\nOr use the following command to also remove temporary SCons files:\n\n    $ rm -rf build .sconf_temp .sconsign.dblite\n\nRunning FreeNOS\n===============\n\nTo run the autotester of FreeNOS on the host OS, run:\n\n    $ scons test\n\nTo run the same autotester on FreeNOS under Qemu, run:\n\n    $ scons qemu_test\n\nTo start FreeNOS in a Qemu virtual machine with a serial console,\nuse the following command:\n\n    $ scons qemu\n\nTo debug FreeNOS using GDB, you need to build with the build variable DEBUG=True.\nDebugging symbols must available in the compiled programs which the debugger needs to\ntranslate between source code, CPU instructions and vice versa. Compiler optimizations\nare disabled with DEBUG=True, which gives reduced performance but improved\ndebugging experience. By default, the DEBUG build variable is already set to True.\n\nIn case you have configured your build.conf with DEBUG=False, you can pass it on\nthe commandline (or edit your build.conf to set DEBUG to True):\n\n    $ scons DEBUG=True\n\nEnsure that your host OS has GDB available for debugging the target architecture (Intel or ARM).\nFor Ubuntu:\n\n    $ sudo apt-get install gdb-multiarch\n\nOpen two terminals. In the first terminal, launch FreeNOS in Qemu with the internal gdbserver enabled:\n\n    $ scons qemu_debug\n\nIn the second terminal, start GDB and connect to the Qemu internal gdbserver using:\n\n    $ gdb-multiarch ./build/intel/pc/kernel/intel/pc/kernel\n    (gdb) target remote localhost:1234\n\nYou can now use standard GDB commands to interactively debug the FreeNOS kernel for intel.\nSimilarly, you can also debug a user program (./build/intel/pc/bin/XXX). Note that when\ndebugging user programs, the mapped virtual memory changes frequently due to scheduling.\nWhen you set a breakpoint on a virtual memory address, for example a function, it can happen\nthat another program is scheduled and executes on the same virtual address which incorrectly\ntriggers the breakpoint. In order to only trigger the breakpoint for a selected user program,\nyou can put a condition on a breakpoint that matches the process name:\n\n    (gdb) condition 1 $_streq((char *)0xe0000000, \"./server/datastore/server\")\n\nThe above command puts a condition on the breakpoint with index number 1 that says it should\nonly halt execution when the program name string equals \"./server/datastore/server\".\n\nintel/pc\n--------\n\nFor Intel targets, you can also launch Qemu using the graphical VGA console (using SDL):\n\n    $ scons qemu_sdl\n\nTo test FreeNOS on real hardware, write the boot ISO to a bootable device, such as an USB disk.\nInsert the USB disk to your host OS and find the appropriate device name:\n\n    $ fdisk -l\n\nAlternatively, use the dmesg command to find the device name. Write the boot ISO\nusing the following command, where sdX is the name of the USB disk device.\nNote: make sure to select the correct device to prevent data loss:\n\n    $ sudo dd if=build/intel/pc/boot.iso of=/dev/sdX\n    $ sudo sync\n\nInsert the USB disk device to the target system and make sure to choose it as\nboot device when the computer starts (e.g. via BIOS). You should see the FreeNOS VGA console.\n\narm/raspberry\n-------------\n\nTo build FreeNOS for running on the Raspberry Pi 1, use the provided build.conf file\nand rebuild the system:\n\n    $ cp config/arm/raspberry/build.conf .\n    $ scons\n\nTo test FreeNOS for the raspberry pi 1 under Qemu, rebuild the system\nwith the QEMU_BUILD build variable set to True:\n\n    $ scons QEMU_BUILD=True\n    $ scons qemu\n\nTo test on a real Raspberry Pi using SD card, download the latest Raspbian 'Lite' image\nfrom https://www.raspberrypi.org/downloads/raspbian/ and unzip it. Insert the SD card to\nyour reader/writer slot on your host OS and find the appropriate device name using:\n\n    $ fdisk -l\n\nAlternatively, use the dmesg command to find the device name. Write the Raspbian image to the\nSD card using the following command, where sdX is the name of the SD card device.\nNote: make sure to select the correct device to prevent data loss:\n\n    $ sudo dd if=/path/to/raspbian/image.img of=/dev/sdX\n    $ sudo sync\n\nRe-insert the SD-card to auto mount it on your host OS. Copy the FreeNOS raspberry pi kernel executable\nto the '/boot' partition on the Raspbian image using (on Ubuntu):\n\n    $ sudo cp build/arm/raspberry/kernel.img /media/boot/kernel.img\n    $ sudo sync\n    $ sudo umount /media/boot\n\nYou will need a USB-to-TTL-serial cable to connect to the Raspberry Pi UART.\nAny USB-to-TTL-serial cable will work, for example the Adafruit USB-to-TTL-serial cable:\n\n    https://www.adafruit.com/product/954\n\nConnect your USB-to-serial cable to the Raspberry Pi using the GPIO pins:\n\n    [ ] [ ]\n    [ ] [X]  Pin 4  (V5)     \u003c---  Red (only needed if powered via USB)\n    [ ] [X]  Pin 6  (Ground) \u003c---  Black\n    [ ] [X]  Pin 8  (RX)     \u003c---  White\n    [ ] [X]  Pin 10 (TX)     \u003c---  Green\n    [ ] [ ]\n    [ ] [ ]\n    [ ] [ ]\n    [ ] [ ]\n    [ ] [ ]\n\nAlso see the following tutorial by Adafruit on connecting the serial cable to the Raspberry Pi:\n\n    https://learn.adafruit.com/adafruits-raspberry-pi-lesson-5-using-a-console-cable/connect-the-lead\n\nConnect your Raspberry Pi to the host to power it via USB or use an external power adapter.\nOn the host OS, launch a serial console client program such as minicom and connect it to the\nUSB serial device (baudrate 115200):\n\n    $ minicom -D /dev/ttyUSB0\n\nYou should now see the FreeNOS console output.\n\narm/raspberry2\n--------------\n\nFollow the same instructions as for the Raspberry Pi 1 above, but use the Raspberry Pi 2\nconfiguration file instead to build FreeNOS:\n\n    $ cp config/arm/raspberry2/build.conf .\n    $ scons\n\nWhen copying the kernel executable to the SD card '/boot' partition, use the 'kernel7.img' filename\nto make sure the Raspberry Pi bootloader correctly starts the kernel (ARMv7):\n\n    $ cp build/arm/raspberry/kernel.img /media/boot/kernel7.img\n\nAdditionally, for raspberry pi 2 and newer, add the following to the /boot/config.txt\nfile to ensure the first UART is available on GPIO pins 8 and 10:\n\n    dtoverlay=pi3-miniuart-bt\n    enable_uart=1\n\narm/sunxi-h3\n------------\n\n### U-Boot on SD Card ###\n\nFreeNOS has support for ARM boards with Allwinner H3 System-on-chips such as the Orange Pi PC\nand Orange Pi Zero (H2+ is a H3 variant). To build FreeNOS for the Allwinner H3, copy the\nprovided configuration file:\n\n    $ cp config/arm/sunxi-h3/build.conf .\n    $ scons\n\nThe kernel image in U-Boot format can be copied to an SD card with U-Boot installed:\n\n    $ cp build/arm/sunxi-h3/kernel/arm/sunxi-h3/kernel.ub /media/sdcard/kernel.ub\n\nTo install U-Boot mainline on the SD-card, clone the source and select the proper\nconfiguration for your board (Orange Pi PC: orangepi_pc_defconfig, Orange Pi Zero: orangepi_zero_defconfig):\n\n    $ git clone https://gitlab.denx.de/u-boot/u-boot u-boot-git\n    $ cd u-boot-git\n    $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make mrproper\n    $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make orangepi_pc_defconfig\n\nTo change the default configuration, enter the Kconfig interactive editor using:\n\n    $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make menuconfig\n\nBefore building, you need to select the following configuration item:\n\n    Device Tree Control \u003e Provider for DTB for DT Control \u003e Embedded DTB\n\nTo build the U-Boot binary, simply use make without any arguments:\n\n    $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make\n\nThe file u-boot-sunxi-with-spl.bin is now ready to be written to the SD card:\n\n    $ sudo dd if=u-boot-sunxi-with-spl.bin of=/dev/sdXXX bs=1024 seek=8 conv=notrunc\n\nInsert the SD card in the target board with the UART console connected and enter the following commands\nin the U-Boot interactive console to load and start FreeNOS:\n\n    =\u003e setenv bootm_boot_mode sec\n    =\u003e fatload mmc 0:1 0x400fffc0 kernel.ub\n    14757888 bytes read in 670 ms (21 MiB/s)\n    =\u003e bootm 0x400fffc0\n\nYou may also choose to download the FreeNOS kernel image via the network. To use a static IP address and server use:\n\n    =\u003e setenv image kernel.ub\n    =\u003e setenv image_addr 0x400fffc0\n    =\u003e setenv bootm_boot_mode sec\n    =\u003e setenv ipaddr 172.16.10.120\n    =\u003e setenv serverip 172.16.10.1\n    =\u003e tftp $image_addr $serverip:$image\n    =\u003e bootm $image_addr\n\nTo retrieve an IP address using DHCP, use the 'dhcp' command prior to downloading and booting:\n\n    =\u003e setenv bootm_boot_mode sec\n    =\u003e dhcp\n    =\u003e tftp 0x400fffc0 kernel.ub\n    =\u003e bootm 0x400fffc0\n\n### U-Boot on SPI Flash ###\n\nAlternatively, the Orange Pi Zero board contains a small SPI flash which can also be used to install U-Boot.\nThis can be done using the Allwinner Sunxi Tools via a special FEL mode via USB. First clone and build the sunxi-tools:\n\n    $ git clone https://github.com/linux-sunxi/sunxi-tools\n    $ cd sunxi-tools\n\nConnect your board via USB-cable to your PC and verify that FEL mode works:\n\n    $ sunxi-fel ver\n\nWhen you have build U-Boot using the previous steps, write the U-Boot binary to the flash with:\n\n    $ ./sunxi-fel -v -p spiflash-write 0 ../u-boot/u-boot-sunxi-with-spl.bin\n\nWith this change the board will not enter FEL mode anymore. In order to re-write the SPI flash, you can erase\nthe flash using Armbian. Download the latest Armbian image for Orange Pi Zero at https://www.armbian.com/orange-pi-zero/.\nMount the image and edit the file /boot/armbianEnv.txt. Add the following entries to enable /dev/mtd0:\n\n    spi-jedec-nor\n    param_spinor_spi_bus=0\n\nStart the board from the modified Armbian image and run the following commands to erase the SPI flash:\n\n    $ sudo apt-get install mtd-utils\n    $ sudo flash_erase /dev/mtd0 0 0200000\n\n### U-Boot on Qemu/TFTP ###\n\nAn alternative for testing the boot process using U-Boot is with Qemu. You can start U-Boot via Qemu as the kernel\nto be loaded using -kernel and provide tftp= argument for -netdev to enable the integrated TFTP server in Qemu.\nThe following commands can be used to download the FreeNOS image via TFTP and boot it:\n\n    $ qemu-system-arm -M orangepi-pc -kernel /path/to/u-boot/u-boot -nographic \\\n         -net nic,id=net0 -netdev user,id=hub0port0,tftp=/path/to/FreeNOS/\n    ...\n    =\u003e setenv bootm_boot_mode sec\n    =\u003e dhcp\n    =\u003e tftp 0x400fffc0 build/arm/sunxi-h3/kernel/arm/sunxi-h3/kernel.ub\n    =\u003e bootm 0x400fffc0\n\nUsing FreeNOS\n=============\n\nWhen FreeNOS starts the system will print bootup output and present the system\nlogin prompt. Currently the login will accept any username value and does not\nask for a password. The FreeNOS interactive console prompt looks like the following:\n\n    (localhost) / #\n\nFreeNOS has a UNIX-like interface and you may enter any of the commands available\nin the /bin directory:\n\n    (localhost) / # ls bin\n\nFor example, the 'ps' command prints a list of all processes running in the system:\n\n    (localhost) / # ps\n\nYou can also run the fully automatic autotester inside Qemu or on real hardware\nusing the following command:\n\n    (localhost) / # /test/run\n\nTo view some information about the FreeNOS version and hardware settings\nyou can use the 'sysinfo' command:\n\n    (localhost) / # sysinfo\n\nThe '/' in the prompt indicates the current active directory. Change it with the 'cd'\nbuilt-in shell command:\n\n    (localhost) / # cd /tmp\n    (localhost) /tmp #\n\nThe FreeNOS shell has several built-in commands, use the 'help' command\nto view all the built-in shell commands:\n\n    (localhost) / # help\n\nFreeNOS on Allwinner H2+/H3 boards support networking. You can see the current state\nof the network stack with:\n\n    (localhost) / # netctl\n\nTo assign a static IP address you can write the IPV4 address file in the corresponding device:\n\n    (localhost) / # write /network/sun8i/ipv4/address 172.16.10.90\n\nTo obtain an address via DHCP, you can start the DHCP client with:\n\n    (localhost) / # dhcpc sun8i\n\nWhen the device has a valid IPV4 address you can send out an ICMP ping using:\n\n    (localhost) / # netping -i sun8i 172.16.10.1\n\nExample application program for calculating prime numbers is the /bin/prime command.\nTo let it compute all prime numbers up to 1024 and output the prime number results use:\n\n    (localhost) / # prime --stdout 1024\n\nThe prime command also has a multicore capable variant variant called 'mpiprime' which uses\nthe Message Passing Interface (MPI) library. The mpiprime program can compute the prime numbers\nin parallel using multiple cores. To run it via the console and let the shell measure the time taken use:\n\n    (localhost) / # time mpiprime 2000000\n\nYou can compare the time result versus the time take of the single core program\nwhere it computes the same number of primes:\n\n    (localhost) / # time prime 2000000\n\nAdditionally, it is possible on the Allwinner H2+/H3 (arm/sunxi-h3) target to start MPI programs\nvia the network on multiple nodes running FreeNOS. You can do that by starting the corresponding\nMPI program which is compiled on your host OS and uses the MPI library host code to communicate with\nthe remote nodes via ethernet. You need to provide a configuration file that specifies the list of\nIP addresses and core identifiers. For example, see the file config/host/mpihosts.txt which is configured\nto use the local Qemu program for testing. Start the QEMU instance with MPI enabled using:\n\n    $ scons qemu_mpi\n\nIn another terminate, start the MPI ping test program that communicates with the Qemu instance with:\n\n    $ ./build/host/bin/mpiping/mpiping ./config/host/mpihosts.txt\n\nYou can also start the MPI variant of the prime program via the network with:\n\n    $ ./build/host/bin/mpiprime/mpiprime ./config/host/mpihosts.txt 3000000\n\nProvide your own configuration file with an arbitrary list of IP addresses to run\nMPI programs on your own compute cluster.\n\nJenkins Continuous Integration\n==============================\n\nAutomated with Vagrant\n----------------------\nThe installation and configuration of continuous integration for FreeNOS is fully automated\nusing Vagrant (https://www.vagrantup.com/). Vagrant is an open source program which automates\nthe creation and configuration of virtual machines of various types of backends, for example\nVirtual Box and libvirt / KVM. FreeNOS provides a few script files which can be used by Vagrant\nto create the Jenkins master and slave nodes automatically, configure them and start build jobs.\n\nInstall Vagrant from the official website at https://www.vagrantup.com/ or via your OS package\nmanager. For example, on Ubuntu Linux:\n\n    $ sudo apt-get install vagrant\n\nVagrant must have a backend virtual machine hypervisor to run the actual VM's. This can be\ndone using any of the supported backend, for example VirtualBox or libvirt/KVM. For full details\non how to setup Vagrant for your VM backend, please visit: https://www.vagrantup.com/docs/installation/.\n\nTo install and use libvirt / KVM using Vagrant on Ubuntu Linux, first ensure that hardware virtualization\nextensions for your processor is enabled in the BIOS of your computer. After that, use the following\ncommands to install libvirt, KVM and Vagrant libvirt support:\n\n    $ sudo apt-get install vagrant-libvirt libvirt-bin libvirt-dev qemu-kvm qemu-utils qemu\n\nOn Ubuntu 20.04:\n\n    $ sudo apt-get install libvirt-clients libvirt-daemon-system qemu-kvm vagrant-libvirt\n\nAdd yourself to the libvirt usergroup in order to use the libvirt installation:\n\n    $ sudo usermod -a -G libvirt my_userid\n\nTest if libvirt with KVM is working properly:\n\n    $ virsh list\n\nIf you do not get any errors, libvirt with KVM should be working.\n\nTo bring up the master machine, install it and start jenkins, use:\n\n    $ cd /path/to/FreeNOS\n    $ cd support/jenkins\n    $ vagrant up master\n\nAfter installation completes, open your webbrowser at http://localhost:8888/ to use Jenkins.\nThe default username and password are: admin, admin.\n\nTo bring up the Ubuntu slave use:\n\n    $ vagrant up ubuntu1804\n\nSimilarly, bring up the FreeBSD 12.0 slave with:\n\n    $ vagrant up freebsd12\n\nWhen you wish to automatically bring up all the machines, install and configure them and also\nautomatically run the jobs, simply use the following command. Note that this will consume\nlots of CPU and RAM:\n\n    $ vagrant up\n\nAfter making changes to the FreeNOS code, it is possible to re-run the jenkins jobs by\nprovisioning the slaves again with:\n\n    $ vagrant provision freebsd12\n    $ vagrant provision ubuntu1804\n\nThis will ensure the slaves are fully updated to the latest OS and compilers and runs\nthe Jenkins jobs for all available configurations.\n\nNote for windows users with Vagrant: do not set core.autocrlf to true in git, as otherwise the\nsource files will get \\r\\n characters added, leading to errors in the bash scripts.\n\nJenkins Master (Manual Install)\n-------------------------------\n\nThe following sections describe how to install Jenkins manually on your host OS for continuous\nintegration of FreeNOS. Install Jenkins on your host OS using your favorite package manager or\nfrom the official website (https://jenkins.io/). Follow the installation wizard instructions and\nafter installation go to the Jenkins web interface at: http://localhost:8080\n\nAfter installation, navigate to: Manage Jenkins \u003e Manage Plugins\nMake sure the following plugins are installed. Choose the plugins from the 'Available' tab to find the plugins\nwhich are not yet installed:\n\n- Matrix Project Plugin (https://wiki.jenkins-ci.org/display/JENKINS/Matrix+Project+Plugin)\n- Matrix Combinations Plugin (https://wiki.jenkins-ci.org/display/JENKINS/matrix+combinations+plugin)\n- Node and Label Parameter Plugin (https://wiki.jenkins-ci.org/display/JENKINS/NodeLabel+Parameter+Plugin)\n- Libvirt Slaves Plugin (https://wiki.jenkins.io/display/JENKINS/Libvirt+Slaves+Plugin)\n- SSH Plugin (https://wiki.jenkins-ci.org/display/JENKINS/SSH+plugin)\n- Workspace Cleanup Plugin (https://wiki.jenkins-ci.org/display/JENKINS/Workspace+Cleanup+Plugin)\n\nAfter finishing Jenkins configuration, install KVM and Libvirt on your host OS. For Ubuntu use:\n\n    $ sudo apt-get install qemu-kvm libvirt-bin virtinst\n\nConnect Jenkins to libvirt via SSH, navigate to: Manage Jenkins \u003e Configure System\nChoose 'Add a new cloud' and select 'Hypervisor Type': QEMU,\n'Hypervisor Host': localhost and choose your desired SSH username.\n\nPress 'Advanced' to choose authentication parameters and press 'Test Connection' to\nverify Jenkins can access libvirt via SSH. For Ubuntu, you need to ensure the SSH user\nis in the 'kvm' and 'libvirtd' groups:\n\n    $ sudo usermod -a -G kvm,libvirtd jenkins\n\nJenkins need to find the KVM guests by their hostname. You can either manually configure\nthe DNS hostname to IP translation in the /etc/hosts file or automatically using the\ninternal libvirt DNSMasq server.\n\nTo setup automatic DNS translation in KVM, first edit the 'default' libvirt network interface\nto add the '.kvm' local-only domain:\n\n    $ virsh net-edit default\n\nAdd the following line inside the \u003cnetwork\u003e....\u003c/network\u003e tag:\n\n    \u003cdomain name='kvm' localOnly='yes'/\u003e\n\nTo use the libvirt internal DNSMasq server on your host, you may change the /etc/resolv.conf\nfile to add the following:\n\n    nameserver 192.168.122.1\n\nIf your host OS uses NetworkManager for networking, add the following files:\n\n    $ sudo -s\n    # cat \u003e /etc/NetworkManager/conf.d/localdns.conf\n    [main]\n    dns=dnsmasq\n\n    # cat \u003e /etc/NetworkManager/dnsmasq.d/libvirt_dnsmasq.conf\n    server=/kvm/192.168.122.1\n\nEnsure that all KVM guests have their hostname set in the .kvm domain (e.g. someguest.kvm).\nRestart libvirt and optionally NetworkManager to apply the changes:\n\n    $ sudo /etc/init.d/libvirt-bin restart\n    $ sudo /etc/init.d/NetworkManager restart\n\nYou should now be able to resolve the hostnames of your guests in the .kvm domain after they\nare started, for example:\n\n    $ virsh start ubuntu-1804\n    $ host ubuntu-1804.kvm\n\nAlso visit the following page for more details on this automatic DNS setup for KVM:\nhttps://liquidat.wordpress.com/2017/03/03/howto-automated-dns-resolution-for-kvmlibvirt-guests-with-a-local-domain/\n\nFreeBSD 12.0 Slave (Manual Install)\n-----------------------------------\n\nRun the example installation script in ./support/jenkins/freebsd-12.sh from the FreeNOS sources\nto setup the KVM guest with FreeBSD 12.0. Also see the comments in the installation script for more info:\n\n    jenkins@host$ cd support/jenkins\n    jenkins@host$ ./freebsd-12.sh\n\nTo configure the FreeBSD 12.0 slave in Jenkins for building FreeNOS, you first need to\nmake sure the Jenkins user can login to the slave using SSH. Optionally, you can\nconfigure this with public key authentication:\n\n    jenkins@host$ virsh start freebsd-12\n    jenkins@host$ ssh-keygen\n    jenkins@host$ ssh-copy-id jenkins@freebsd-12.kvm\n\nTest if the Jenkins user can login to the FreeBSD KVM guest with SSH (via password or key):\n\n    jenkins@host$ ssh jenkins@freebsd-12.kvm\n\nCopy the example node configuration XML file to the Jenkins installation directory:\n\n    jenkins@host$ mkdir /var/lib/jenkins/nodes/freebsd-12-test\n    jenkins@host$ cp freebsd-12.node.xml /var/lib/jenkins/nodes/freebsd-12-test/config.xml\n\nAlso copy the job configuration XML file to the Jenkins installation directory:\n\n    jenkins@host$ mkdir /var/lib/jenkins/jobs/FreeNOS-freebsd12-test\n    jenkins@host$ cp freebsd-12.job.xml /var/lib/jenkins/jobs/FreeNOS-freebsd12-test/config.xml\n\nRestart the Jenkins server to use the new configuration files:\n\n    $ sudo /etc/init.d/jenkins restart\n\nJenkins still needs authentication credentials to connect to the slave. Navigate to:\n\n    Manage Jenkins \u003e Manage Nodes \u003e freebsd-12 \u003e Configure\n\nIn the sub-menu 'Secondary launch method', under 'Launch agents via SSH',\nselect existing SSH credentials to let jenkins use it to login to the slave node\nor add a new credentials with the 'Add' button. If you generated an SSH key for\nthe jenkins user on the host OS, insert the SSH private key or provide username/password.\n\nPress the 'Save' button to finish and use 'Launch Agent' to test the connection.\n\nYou can now press the 'Schedule a Build' button on the 'FreeNOS-freebsd12' build job to test.\n\nUbuntu 18.04 Slave\n------------------\n\nFollow the same instructions as the FreeBSD 12.0 Slave above and just\nreplace the slave name with 'ubuntu-1804'.\n\nAuthors\n=======\n\nThe FreeNOS code has been written from scratch by Niek Linnenbank.\nPeople who contributed to FreeNOS are:\n\n* Dan Rulos (AmayaOS)\n* Coen Bijlsma (libparse, srv/time)\n* Ed Schouten (libteken)\n* Alexander Schrijver (OpenBSD patches)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnieklinnenbank%2FFreeNOS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnieklinnenbank%2FFreeNOS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnieklinnenbank%2FFreeNOS/lists"}