diff options
Diffstat (limited to 'README.rst')
| -rw-r--r-- | README.rst | 853 |
1 files changed, 853 insertions, 0 deletions
diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..9b328078 --- /dev/null +++ b/README.rst @@ -0,0 +1,853 @@ +RTEMS LibBSD +************ + +Welcome to building LibBSD for RTEMS using Waf. This package is a library +containing various parts of the FreeBSD kernel ported to RTEMS. The library +replaces the networking port of FreeBSD in the RTEMS kernel sources. This +package is designed to be updated from the FreeBSD kernel sources and contains +more than just the networking code. + +To build this package you need a current RTEMS tool set for your architecture, +and a recent RTEMS kernel for your BSP installed. If you already have this, you +can skip to step 5 of the build procedure. + +Building and Installing LibBSD +============================== + +The following instructions show you how to build and install the RTEMS Tool +Suite for the ``arm`` target, the RTEMS kernel using the +``arm/xilinx_zynq_a9_qemu`` Board Support Package (BSP), and the LibBSD for this +BSP. + +The Waf build support for RTEMS requires you provide your BSP name as an +architecture and BSP pair. You must provide both or Waf will generate an error +message during the configure phase. + +We will build an Xilinx Zynq Qemu BSP using the name +``arm/xilinx_zynq_a9_qemu``. You can copy and paste the shell commands below to +do this. The individual steps are explained afterwards. + +.. code-block:: none + + sandbox="$PWD/sandbox" + mkdir sandbox + cd "$sandbox" + git clone git://git.rtems.org/rtems-source-builder.git + git clone git://git.rtems.org/rtems.git + git clone git://git.rtems.org/rtems-libbsd.git + cd "$sandbox" + cd rtems-source-builder/rtems + ../source-builder/sb-set-builder --prefix="$sandbox/rtems/6" 6/rtems-arm + cd "$sandbox" + cd rtems + echo -e "[arm/xilinx_zynq_a9_qemu]" > config.ini + ./waf configure --prefix "$sandbox/rtems/6" + ./waf + ./waf install + cd "$sandbox" + cd rtems-libbsd + git submodule init + git submodule update rtems_waf + ./waf configure --prefix="$sandbox/rtems/6" \ + --rtems-bsps=arm/xilinx_zynq_a9_qemu \ + --buildset=buildset/default.ini + ./waf + ./waf install + ../rtems/6/bin/rtems-test --rtems-bsp=xilinx_zynq_a9_qemu build + +1. Create a sandbox directory: + + .. code-block:: none + + $ sandbox="$PWD/sandbox" + $ mkdir sandbox + +2. Clone the repositories: + + .. code-block:: none + + $ cd "$sandbox" + $ git clone git://git.rtems.org/rtems-source-builder.git + $ git clone git://git.rtems.org/rtems.git + $ git clone git://git.rtems.org/rtems-libbsd.git + +3. Build and install the tools: + + .. code-block:: none + + $ cd "$sandbox" + $ cd rtems-source-builder/rtems + $ ../source-builder/sb-set-builder --prefix="$sandbox/rtems/6" 6/rtems-arm + +4. Build and install the RTEMS Board Support Packages (BSP) you want to use: + + .. code-block:: none + + $ cd "$sandbox" + $ cd rtems + $ echo -e "[arm/xilinx_zynq_a9_qemu]" > config.ini + $ ./waf configure --prefix "$sandbox/rtems/6" + $ ./waf + $ ./waf install + +5. Populate the ``rtems_waf`` git submodule. Note, make sure you specify + ``rtems_waf`` or the FreeBSD kernel source will be cloned: + + .. code-block:: none + + $ cd "$sandbox" + $ cd rtems-libbsd + $ git submodule init + $ git submodule update rtems_waf + +6. Run Waf's configure with your specific settings. In this case the path to + the tools and RTEMS are provided on the command line and so do not need to + be in your path or environment, see comment below. You can use + ``--rtems-archs=arm,sparc,i386`` or + ``--rtems-bsps=arm/xilinx_zynq_a9_qemu,sparc/sis,i386/pc586`` to build for + more than BSP at a time. Note, you must provide the architecture and BSP as + a pair. Providing just the BSP name will fail. This call also explicitly + provides a buildset via the ``--buildset=buildset/default.ini`` option. If no + buildset is provided the default one (which is the same as the one provided + explicitly here) will be used. You can also provide multiple buildsets as a + coma separated list or via multiple ``--buildset=x`` options. + + .. code-block:: none + + $ cd "$sandbox" + $ cd rtems-libbsd + $ ./waf configure --prefix="$sandbox/rtems/6" \ + --rtems-bsps=arm/xilinx_zynq_a9_qemu \ + --buildset=buildset/default.ini + +7. Build and install. The LibBSD package will be installed into the prefix + provided to configure: + + .. code-block:: none + + $ cd "$sandbox" + $ cd rtems-libbsd + $ ./waf + $ ./waf install + +9. Run the tests: + + .. code-block:: none + + $ cd "$sandbox" + $ cd rtems-libbsd + $ ../rtems/6/bin/rtems-test --rtems-bsp=xilinx_zynq_a9_qemu build + +It is good practice to keep your environment as empty as possible. Setting +paths to tools or specific values to configure or control a build is dangerous +because settings can leak between different builds and change what you expect a +build to do. The Waf tool used here lets you specify on the command line the +tools and RTEMS paths and this is embedded in Waf's configuration information. +If you have a few source trees working at any one time with different tool sets +or configurations you can easly move between them safe in the knowledge that +one build will not infect another. + +Buildsets +========= + +Note that the LibBSD supports different buildsets. These can be selected with +the ``--buildset=some.ini`` option during the configure phase. Take a look at +the comments in ``buildset/*.ini`` to see which build sets are officially +supported. + +You can also create and provide your own buildset configuration. But remember +that it's quite easy to break something by disabling the wrong modules. Only +the configurations in the ``buildset`` directory are officially maintained. + +Initialization +============== + +To initialise the LibBSD create a suitable ``rc.conf`` file. The FreeBSD man +page `RC.CONF(5) <https://www.freebsd.org/cgi/man.cgi?rc.conf>`_ provides the +details needed to create a suitable format file + +You can call one of three functions to run the initialisation once LibBSD has +initialised: + +* ``rtems_bsd_run_etc_rc_conf()``: Run ``/etc/rc.conf``. +* ``rtems_bsd_run_rc_conf()``: Run a user supplied file. +* ``rtems_bsd_run_rc_conf_script()``: Run the in memory line feed separated text string. + +For exapmle: + +.. code-block:: c + + void + network_init(void) + { + rtems_status_code sc; + + sc = rtems_bsd_initialize(); + assert(sc == RTEMS_SUCCESSFUL); + + rtems_bsd_run_etc_rc_conf(true); /* verbose = true */ + } + +By default the networking support is builtin. Other directives can be added and +are found in ``machine/rtems-bsd-rc-conf-directives.h``. Please check the file +for the list. + +The following network names are supported: + +.. code-block:: none + + cloned_interfaces + ifconfig_'interface' + defaultrouter + hostname + +For example: + +.. code-block:: none + + # + # My BSD initialisation. + # + hostname="myhost" + cloned_interfaces="vlan0 vlan1" + ifconfig_re0="inet inet 10.10.10.10 netmask 255.255.255.0" + fconfig_vlan0="inet 10.11.10.10 255.255.255.0 vlan 101 vlandev re0" + defaultrouter="10.10.10.1" + +You can also intialise the LibBSD using code. The following code to +initialize the LibBSD: + +.. code-block:: c + + #include <assert.h> + #include <sysexits.h> + + #include <rtems/bsd/bsd.h> + + void + network_init(void) + { + rtems_status_code sc; + int exit_code; + + sc = rtems_bsd_initialize(); + assert(sc == RTEMS_SUCCESSFUL); + + exit_code = rtems_bsd_ifconfig_lo0(); + assert(exit_code == EX_OK); + } + +This performs the basic network stack initialization with a loopback interface. +Further initialization must be done using the standard FreeBSD network +configuration commands +`IFCONFIG(8) <http://www.freebsd.org/cgi/man.cgi?query=ifconfig&sektion=8>`_ +using ``rtems_bsd_command_ifconfig()`` and +`ROUTE(8) <http://www.freebsd.org/cgi/man.cgi?query=route&sektion=8>`_ +using ``rtems_bsd_command_route()``. For an example, please have a look at +`default-network-init.h <testsuite/include/rtems/bsd/test/default-network-init.h>`_. + +Task Priorities and Stack Size +============================== + +The default task priority is 96 for the interrupt server task (name "IRQS"), 98 +for the timer server task (name "TIME") and 100 for all other tasks. The +application may provide their own implementation of the +``rtems_bsd_get_task_priority()`` function if different values are desired (for +example in the translation unit which calls ``rtems_bsd_initialize()``). + +The task stack size is determined by the ``rtems_bsd_get_task_stack_size()`` +function which may be provided by the application in case the default is not +appropriate. + +Size for Allocator Domains +========================== + +The size for an allocator domain can be specified via the +``rtems_bsd_get_allocator_domain_size()`` function. The application may provide +their own implementation of the ``rtems_bsd_get_allocator_domain_size()`` +function (for example in the module which calls ``rtems_bsd_initialize()``) if +different values are desired. The default size is 8MiB for all domains. + +Redirecting or Disabling the Output +=================================== + +A lot of system messages are printed to the ``stdout`` by default. If you want to +redirect them you can overwrite the default print handler. That can even be done +before the libbsd initialization to catch all messages. An example would look +like follows: + +.. code-block:: c + + int my_vprintf_handler(int level, const char *fmt, va_list ap) { + /* Do something with the messages. */ + + return number_of_printed_chars; + } + + ... + /* In your initialization: */ + rtems_bsd_vprintf_handler old; + old = rtems_bsd_set_vprintf_handler(my_vprintf_handler); + ... + +As a special case, you can set the ``rtems_bsd_vprintf_handler_mute(...)`` +provided by LibBSD to suppress all output. + +Branches +======== + +master + This branch is intended for the RTEMS master which tracks the FreeBSD + master branch. This branch must be used for libbsd development. Back + ports to the 6-freebsd-12 are allowed. + +6-freebsd-12 + This branch is intended for RTEMS 6 which tracks the FreeBSD stable/12 + branch. This branch is maintained and regular updates from FreeBSD are + planned. It is recommended for production systems. + +5-freebsd-12 + This branch belongs to the RTEMS 5 release. It is based on FreeBSD + stable/12 branch. It is recommended for production systems that use + RTEMS 5. + +5 + This branch belongs to the RTEMS 5 release. It is based on a FreeBSD + development version. This branch is unmaintained. Use 5-freebsd-12 for + RTEMS 5. + +freebsd-9.3 + Is the branch for some RTEMS version with a FreeBSD 9.3 baseline. This + branch is unmaintained. It is recommended to update to RTEMS 5 or 6. + +4.11 + Is the branch for the RTEMS 4.11 release series. This branch is + unmaintained. It is recommended to update to RTEMS 5 or 6. + +Features +======== + +The following features are available in LibBSD. Some features need device +driver support for a particular target platform. + +* `BPF(4) <http://www.freebsd.org/cgi/man.cgi?query=bpf&sektion=4>`_: Berkeley Packet Filter +* `DHCPCD(8) <http://roy.marples.name/projects/dhcpcd/index>`_: DHCP client +* `dns_sd.h <mDNSResponder/mDNSShared/dns_sd.h>`_: DNS Service Discovery +* `GETHOSTBYNAME(3) <http://www.freebsd.org/cgi/man.cgi?query=gethostbyname&sektion=3>`_: Get network host entry +* `IF_BRIDGE(4) <http://www.freebsd.org/cgi/man.cgi?query=if_bridge&sektion=4>`_: Network bridge device +* `INET(4) <http://www.freebsd.org/cgi/man.cgi?query=inet&sektion=4>`_: Internet protocol family +* `INET6(4) <http://www.freebsd.org/cgi/man.cgi?query=inet6&sektion=4>`_: Internet protocol version 6 family +* `IPSEC(4) <http://www.freebsd.org/cgi/man.cgi?query=ipsec&sektion=4>`_: Internet Protocol Security protocol +* `KQUEUE(2) <http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2>`_: Kernel event notification mechanism +* `LAGG(4) <http://www.freebsd.org/cgi/man.cgi?query=lagg&sektion=4>`_: Link aggregation and link failover interface +* `mDNSEmbeddedAPI.h <mDNSResponder/mDNSCore/mDNSEmbeddedAPI.h>`_: Multi-Cast DNS +* `MMC(4) <http://www.freebsd.org/cgi/man.cgi?query=mmc&sektion=4>`_: MultiMediaCard and SD Card bus driver +* `NET80211(4) <http://www.freebsd.org/cgi/man.cgi?query=net80211&sektion=4>`_: Standard interface to IEEE 802.11 devices +* `NVME(4) <http://www.freebsd.org/cgi/man.cgi?query=nvme&sektion=4>`_: NVM Express core driver +* `PCI(4) <http://www.freebsd.org/cgi/man.cgi?query=pci&sektion=4>`_: Generic PCI/PCIe bus driver +* `PF(4) <http://www.freebsd.org/cgi/man.cgi?query=pf&sektion=4>`_: Packet filter +* `POLL(2) <http://www.freebsd.org/cgi/man.cgi?query=poll&sektion=2>`_: Synchronous I/O multiplexing +* `RESOLVER(3) <http://www.freebsd.org/cgi/man.cgi?query=resolver&sektion=3>`_: Resolver routines +* `ROUTE(4) <http://www.freebsd.org/cgi/man.cgi?query=route&sektion=4>`_: Kernel packet forwarding database +* `SELECT(2) <http://www.freebsd.org/cgi/man.cgi?query=select&sektion=2>`_: Synchronous I/O multiplexing +* `SOCKET(2) <http://www.freebsd.org/cgi/man.cgi?query=socket&sektion=2>`_: Create an endpoint for communication +* `SSL(7) <http://www.freebsd.org/cgi/man.cgi?query=ssl&sektion=7>`_: OpenSSL SSL/TLS library +* `SYSCTL(3) <http://www.freebsd.org/cgi/man.cgi?query=sysctl&sektion=3>`_: Get or set system information +* `TCP(4) <http://www.freebsd.org/cgi/man.cgi?query=tcp&sektion=4>`_: Internet Transmission Control Protocol +* `UDP(4) <http://www.freebsd.org/cgi/man.cgi?query=udp&sektion=4>`_: Internet User Datagram Protocol +* `UMASS(4) <http://www.freebsd.org/cgi/man.cgi?query=umass&sektion=4>`_: USB Mass Storage Devices driver +* `UNIX(4) <http://www.freebsd.org/cgi/man.cgi?query=unix&sektion=4>`_: UNIX-domain protocol family +* `USB(4) <http://www.freebsd.org/cgi/man.cgi?query=usb&sektion=4>`_: Universal Serial Bus +* `VLAN(4) <http://www.freebsd.org/cgi/man.cgi?query=vlan&sektion=4>`_: IEEE 802.1Q VLAN network interface + +Commands +======== + +In LibBSD the following ports of FreeBSD command line tools are available. You +can invoke the commands in the RTEMS Shell or through function calls, for +example ``rtems_bsd_command_ifconfig()``. The functions declarations are +available through +`#include <machine/rtems-bsd-commands.h> <rtemsbsd/include/machine/rtems-bsd-commands.h>`_. + +* `ARP(8) <http://www.freebsd.org/cgi/man.cgi?query=arp&sektion=8>`_: Address resolution display and control +* `HOSTNAME(1) <http://www.freebsd.org/cgi/man.cgi?query=hostname&sektion=1>`_: Set or print name of current host system +* `IFCONFIG(8) <http://www.freebsd.org/cgi/man.cgi?query=ifconfig&sektion=8>`_: Configure network interface parameters +* `IFMCSTAT(8) <http://www.freebsd.org/cgi/man.cgi?query=ifmcstat&sektion=8>`_: Dump multicast group management statistics per interface +* `NETSTAT(1) <http://www.freebsd.org/cgi/man.cgi?query=netstat&sektion=1>`_: Show network status +* `NVMECONTROL(8) <http://www.freebsd.org/cgi/man.cgi?query=nvmecontrol&sektion=8>`_: NVM Express control utility +* `OPENSSL(1) <http://www.freebsd.org/cgi/man.cgi?query=openssl&sektion=1>`_: OpenSSL command line tool +* `PFCTL(8) <http://www.freebsd.org/cgi/man.cgi?query=pfctl&sektion=8>`_: Control the packet filter (PF) device +* `PING6(8) <http://www.freebsd.org/cgi/man.cgi?query=ping6&sektion=8>`_: Send ICMPv6 ECHO_REQUEST packets to network hosts +* `PING(8) <http://www.freebsd.org/cgi/man.cgi?query=ping&sektion=8>`_: Send ICMP ECHO_REQUEST packets to network hosts +* `RACOON(8) <http://www.freebsd.org/cgi/man.cgi?query=racoon&sektion=8>`_: IKE (ISAKMP/Oakley) key management daemon +* `ROUTE(8) <http://www.freebsd.org/cgi/man.cgi?query=route&sektion=8>`_: Manually manipulate the routing tables +* `SETKEY(8) <http://www.freebsd.org/cgi/man.cgi?query=setkey&sektion=8>`_: Manually manipulate the IPsec SA/SP database +* `STTY(1) <http://www.freebsd.org/cgi/man.cgi?query=stty&sektion=1>`_: Set the options for a terminal device interface +* `SYSCTL(8) <http://www.freebsd.org/cgi/man.cgi?query=sysctl&sektion=8>`_: Get or set kernel state +* `TCPDUMP(1) <http://www.freebsd.org/cgi/man.cgi?query=tcpdump&sektion=1>`_: Dump traffic on a network +* `VMSTAT(8) <http://www.freebsd.org/cgi/man.cgi?query=vmstat&sektion=8>`_: Report virtual memory statistics +* `WPA_SUPPLICANT(8) <http://www.freebsd.org/cgi/man.cgi?query=wpa_supplicant&sektion=8>`_: WPA/802.11i Supplicant for wireless network devices + +Command specific notes are listed below. + +HOSTNAME(1) + In addition to the standard options the RTEMS version of the HOSTNAME(1) + command supports the -m flag to set/get the multicast hostname of the mDNS + resolver instance. See also ``rtems_mdns_sethostname()`` and + ``rtems_mdns_gethostname()``. + +Packet Filter (PF, Firewall) +============================ + +It is possible to use PF as a firewall. See the +`FreeBSD Handbook <https://docs.freebsd.org/en/books/handbook/firewalls/#firewalls-pf>`_ +for details on the range of functions and for how to configure the firewall. + +Configuration +------------- + +The following is necessary to use PF on RTEMS: + +* You have to provide a ``/etc/pf.os`` file. The firewall can use it for passive + OS fingerprinting. If you don't want to use this feature, the file may contain + nothing except a line of comment (for example "# empty"). + +* If some filters use protocol names (like ``tcp`` or ``udp``) you have to provide a + ``/etc/protocols`` file. + +* If some filters use service names (like ``http`` or ``https``) you have to provide a + ``/etc/services`` file. + +* Create a rule file (normally ``/etc/pf.conf``). See the FreeBSD manual for the + syntax. + +* Load the rule file using the + `pfctl <http://www.freebsd.org/cgi/man.cgi?query=pfctl&sektion=8>`_ + command and enable PF. Please note that the pfctl command needs a lot of + stack. You should use at least RTEMS_MINIMUM_STACK_SIZE + 8192 Bytes of + stack. An example initialisation can look like follows: + + .. code-block:: c + + int exit_code; + char *argv[] = { + "pfctl", + "-f", + "/etc/pf.conf", + "-e", + NULL + }; + + exit_code = rtems_bsd_command_pfctl(ARGC(argv), argv); + assert(exit_code == EXIT_SUCCSESS); + +Known Restrictions +------------------ + +Currently, PF on RTEMS always uses the configuration for memory restricted +systems (on FreeBSD that means systems with less than 100 MB RAM). This is +fixed in ``pfctl_init_options()``. + +Wireless Network (WLAN) +======================= + +The LibBSD provides a basic support for WLAN. Note that currently this support +is still in an early state. The WLAN support is _not_ enabled in the default +buildset. You have to configure LibBSD with the +``--buildset=buildset/everything.ini`` to enable that feature. + +Configuration +------------- + +The following gives a rough overview over the necessary steps to connect to an +encrypted network with an RTL8188EU based WiFi dongle: + +* Reference all necessary module for your BSP. For some BSPs this is already + done in the ``nexus-devices.h``: + + .. code-block:: none + + SYSINIT_MODULE_REFERENCE(wlan_ratectl_none); + SYSINIT_MODULE_REFERENCE(wlan_sta); + SYSINIT_MODULE_REFERENCE(wlan_amrr); + SYSINIT_MODULE_REFERENCE(wlan_wep); + SYSINIT_MODULE_REFERENCE(wlan_tkip); + SYSINIT_MODULE_REFERENCE(wlan_ccmp); + SYSINIT_DRIVER_REFERENCE(rtwn_usb, uhub); + +* Create your wlan device using ifconfig: + + .. code-block:: none + + ifconfig wlan0 create wlandev rtwn0 up + +* Start a ``wpa_supplicant`` instance for that device: + + .. code-block:: none + + wpa_supplicant_fork -Dbsd -iwlan0 -c/media/mmcsd-0-0/wpa_supplicant.conf + +Note that the wpa_supplicant will only be active till the device goes down. A +workaround is to just restart it every time it exits. + +Known Restrictions +------------------ + +* The network interface (e.g. wlan0) is currently not automatically created. It + would be nice, if some service would create it as soon as for example a USB + device is connected. In FreeBSD the names are assigned via rc.conf with lines + like ``wlans_rtwn0="wlan0"``. + +* ``wpa_supplicant`` hast to be started after the device is created. It has to be + restarted every time the connection goes down. Instead of this behaviour, + there should be some service that starts and restarts ``wpa_supplicant`` + automatically if a interface is ready. Probably the dhcpcd hooks could be used + for that. + +* The current ``wpa_supplicant`` implementation is protected with a lock so it can't + be started more than one time. If multiple interface should be used, all have + to be handled by that single instance. That makes it hard to add interfaces + dynamically. ``wpa_supplicant`` should be reviewed thoroughly whether multiple + instances could be started in parallel. + +* The control interface of ``wpa_supplicant`` most likely doesn't work. The wpa_cli + application is not ported. + +IPSec +===== + +The IPSec support is optional in LibBSD. It is disabled in the default build +set. Please make sure to use a build set with ``netipsec = on``. + +Configuration +------------- + +To use IPSec the following configuration is necessary: + +.. code-block:: none + + SYSINIT_MODULE_REFERENCE(if_gif); + SYSINIT_MODULE_REFERENCE(cryptodev); + RTEMS_BSD_RC_CONF_SYSINT(rc_conf_ipsec) + RTEMS_BSD_DEFINE_NEXUS_DEVICE(cryptosoft, 0, 0, NULL); + +Alternatively, you can use the ``RTEMS_BSD_CONFIG_IPSEC`` which also includes the +rc.conf support for ipsec. It's still necessary to include a crypto device in +your config (``cryptosoft`` in the above sample). + +The necessary initialization steps for a IPSec connection are similar to the +steps on a FreeBSD-System. The example assumes the following setup: + +- RTEMS external IP: 192.168.10.1/24 +- RTEMS internal IP: 10.10.1.1/24 +- remote external IP: 192.168.10.10/24 +- remote internal IP: 172.24.0.1/24 +- shared key: "mysecretkey" + +With this the following steps are necessary: + +* Create a gif0 device: + + .. code-block:: none + + ifconfig gif0 create + +* Configure the gif0 device: + + .. code-block:: none + + ifconfig gif0 10.10.1.1 172.24.0.1 + ifconfig gif0 tunnel 192.168.10.1 192.168.10.10 + +* Add a route to the remote net via the remote IP: + + .. code-block:: none + + route add 172.24.0.0/24 172.24.0.1 + +* Create a correct rule set in ``/etc/setkey.conf``: + + .. code-block:: none + + flush; + spdflush; + spdadd 10.10.1.0/24 172.24.0.0/24 any -P out ipsec esp/tunnel/192.168.10.1-192.168.10.10/use; + spdadd 172.24.0.0/24 10.10.1.0/24 any -P in ipsec esp/tunnel/192.168.10.10-192.168.10.1/use; + +* Call ``setkey``: + + .. code-block:: none + + setkey -f /etc/setkey.conf + +* Create a correct configuration in ``/etc/racoon.conf``: + + .. code-block:: none + + path pre_shared_key "/etc/racoon_psk.txt"; + log info; + + padding # options are not to be changed + { + maximum_length 20; + randomize off; + strict_check off; + exclusive_tail off; + } + + listen # address [port] that racoon will listen on + { + isakmp 192.168.10.1[500]; + } + + remote 192.168.10.10 [500] + { + exchange_mode main; + my_identifier address 192.168.10.1; + peers_identifier address 192.168.10.10; + proposal_check obey; + proposal { + encryption_algorithm 3des; + hash_algorithm md5; + authentication_method pre_shared_key; + lifetime time 3600 sec; + dh_group 2; + } + } + + sainfo (address 10.10.1.0/24 any address 172.24.0.0/24 any) + { + pfs_group 2; + lifetime time 28800 sec; + encryption_algorithm 3des; + authentication_algorithm hmac_md5; + compression_algorithm deflate; + } + +* Create a correct configuration in ``/etc/racoon_psk.txt``: + + .. code-block:: none + + 192.168.10.10 mysecretkey + +* Start a ike-daemon (racoon): + + .. code-block:: none + + racoon -F -f /etc/racoon.conf +---- + +All commands can be called via the respective API functions. For racoon there is +a ``rtems_bsd_racoon_daemon()`` function that forks of racoon as a task. + +Alternatively, IPSec can also be configured via rc.conf entries: + +.. code-block:: none + + cloned_interfaces="gif0" + ifconfig_gif0="10.10.1.1 172.24.0.1 tunnel 192.168.10.1 192.168.10.10" + ike_enable="YES" + ike_program="racoon" + ike_flags="-F -f /etc/racoon.conf" + ike_priority="250" + + ipsec_enable="YES" + ipsec_file="/etc/setkey.conf" + +ATTENTION: It is possible that the first packets slip through the tunnel without +encryption (true for FreeBSD as well as RTEMS). You might want to set up a +firewall rule to prevent that. + +Updating RTEMS Waf Support +========================== + +If you have a working libbsd repository and new changes to the ``rtems_waf`` +submodule has been made, you will need update. A ``git status`` will indicate +there are new commits with: + +.. code-block:: none + + $ git status + [ snip output ] + modified: rtems_waf (new commits) + [ snip output ] + +To update: + +.. code-block:: none + + $ git submodule update rtems_waf + +Please make sure you use the exact command or you might find you are cloning +the whole of the FreeBSD source tree. If that happens simply git ^C and try +again. + +FreeBSD Kernel Options +====================== + +You can set FreeBSD kernel options during build configuration with the +--freebsd-option=a,b,c,... configuration command option. This is an advanced +option and should only be used if you are familiar with the internals of the +FreeBSD kernel and what these options do. Each of the comma separated options +is converted to uppercase and passed as a compiler command line define (-D). + +The options are listed in the FreeBSD +`NOTES <https://github.com/freebsd/freebsd/blob/master/sys/conf/NOTES>`_ +file. + +An example to turn on a verbose kernel boot, verbose sysinit and bus debugging +configure with: + +.. code-block:: none + + --freebsd-options=bootverbose,verbose_sysinit,bus_debug + +To enable kernel internal consistency checking use: + +.. code-block:: none + + --freebsd-options=invariants,invariant_support + +SMP Requirements +================ + +In order to support +`EPOCH(9) <https://www.freebsd.org/cgi/man.cgi?query=epoch&apropos=0&sektion=9>`_ +a scheduler with thread pinning support is required. This is the case if you +use the default scheduler configuration. EPOCH(9) is a central synchronization +mechanism of the network stack. + +Configuration for Network Tests +=============================== + +If you need some other IP configuration for the network tests that use a fixed +IP config you can copy ``config.inc`` to a location outside to the source tree and +adapt it. Then use the option ``--net-test-config=NET_CONFIG`` to pass the file to +Waf's configure command. + +.. code-block:: none + + NET_CFG_SELF_IP = 10.0.0.2 + NET_CFG_NETMASK = 255.255.0.0 + NET_CFG_PEER_IP = 10.0.0.1 + NET_CFG_GATEWAY_IP = 10.0.0.1 + +Qemu and Networking +=================== + +You can use the Qemu simulator to run a LibBSD based application and connect it +to a virtual network on your host. + +Networking with TAP Interface +----------------------------- + +One option for networking with Qemu is using a TAP interface (virtual +Ethernet). You can create a TAP interface with these commands on Linux: + +.. code-block:: none + + sudo ip tuntap add qtap mode tap user $(whoami) + sudo ip link set dev qtap up + sudo ip addr add 169.254.1.1/16 dev qtap + +You can show the interface state with the following command: + +.. code-block:: none + + $ ip addr show qtap + 27: qtap: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc pfifo_fast state DOWN group default qlen 1000 + link/ether 8e:50:a2:fb:e1:3b brd ff:ff:ff:ff:ff:ff + inet 169.254.1.1/16 scope global qtap + valid_lft forever preferred_lft forever + +You may have to assign the interface to a firewall zone. + +The Qemu command line varies by board support package, here is an example for +the arm/xilinx_zynq_a9_qemu BSP: + +.. code-block:: none + + qemu-system-arm -serial null -serial mon:stdio -nographic \ + -M xilinx-zynq-a9 -m 256M \ + -net nic,model=cadence_gem \ + -net tap,ifname=qtap,script=no,downscript=no \ + -kernel build/arm-rtems6-xilinx_zynq_a9_qemu-default/media01.exe + +Make sure that each Qemu instance uses its own MAC address to avoid an address +conflict (or otherwise use it as a test). After some seconds it will acquire a +IPv4 link-local address, for example: + +.. code-block:: none + + info: cgem0: probing for an IPv4LL address + debug: cgem0: checking for 169.254.159.156 + +You can connect to the target via telnet, for example: + +.. code-block:: none + + $ telnet 169.254.159.156 + Trying 169.254.159.156... + Connected to 169.254.159.156. + Escape character is '^]'. + + RTEMS Shell on /dev/pty4. Use 'help' to list commands. + TLNT [/] # + +Virtual Distributed Ethernet (VDE) +---------------------------------- + +You can use a Virtual Distributed Ethernet (VDE) to create a network +environment that does not need to run Qemu as root or needing to drop the tap's +privileges to run Qemu. + +VDE creates a software switch with a default of 32 ports which means a single +kernel tap can support 32 Qemu networking sessions. + +To use VDE you need to build Qemu with VDE support. The RSB can detect a VDE +plug and enable VDE support in Qemu when building. On FreeBSD install the VDE +support with: + +.. code-block:: none + + pkg install -u vde2 + +Build Qemu with the RSB. + +To network create a bridge and a tap. The network is 10.10.1.0/24. On FreeBSD +add to your ``/etc/rc.conf``: + +.. code-block:: none + + cloned_interfaces="bridge0 tap0" + autobridge_interfaces="bridge0" + autobridge_bridge0="re0 tap0" + ifconfig_re0="up" + ifconfig_tap0="up" + ifconfig_bridge0="inet 10.1.1.2 netmask 255.255.255.0" + defaultrouter="10.10.1.1" + +Start the VDE switch as root: + +.. code-block:: none + + sysctl net.link.tap.user_open=1 + sysctl net.link.tap.up_on_open=1 + vde_switch -d -s /tmp/vde1 -M /tmp/mgmt1 -tap tap0 -m 660 --mgmtmode 660 + chmod 660 /dev/tap0 + +You can connect to the VDE switch's management channel using: + +.. code-block:: none + + vdeterm /tmp/mgmt1 + +To run Qemu: + +.. code-block:: none + + qemu-system-arm -serial null -serial mon:stdio -nographic \ + -M xilinx-zynq-a9 -m 256M \ + -net nic,model=cadence_gem \ + -net vde,id=vde0,sock=/tmp/vde1 + -kernel build/arm-rtems6-xilinx_zynq_a9_qemu-default/rcconf02.exe |