afonso/core-extra
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

initial pass at removing bsd and code related to using bsd nodes

Browse source
This commit is contained in:
Blake J. Harnden 2018-03-07 12:54:19 -08:00
parent 4858151d7c
commit bc1e3e70c9
62 changed files with 720 additions and 18008 deletions
Download patch file Download diff file Expand all files Collapse all files

282
doc/install.rst
View file

@ -9,14 +9,14 @@
Installation
************
This chapter describes how to set up a CORE machine. Note that the easiest
This chapter describes how to set up a CORE machine. Note that the easiest
way to install CORE is using a binary
package on Ubuntu or Fedora (deb or rpm) using the distribution's package
manager
to automatically install dependencies, see :ref:`Installing_from_Packages`.
Ubuntu and Fedora Linux are the recommended distributions for running CORE. Ubuntu |UBUNTUVERSION| and Fedora |FEDORAVERSION| ship with kernels with support for namespaces built-in. They support the latest hardware. However,
these distributions are not strictly required. CORE will likely work on other
these distributions are not strictly required. CORE will likely work on other
flavors of Linux, see :ref:`Installing_from_Source`.
The primary dependencies are Tcl/Tk (8.5 or newer) for the GUI, and Python 2.6 or 2.7 for the CORE daemon.
@ -50,7 +50,7 @@ Prerequisites
.. index:: Prerequisites
The Linux or FreeBSD operating system is required. The GUI uses the Tcl/Tk scripting toolkit, and the CORE daemon require Python. Details of the individual software packages required can be found in the installation steps.
A Linux operating system is required. The GUI uses the Tcl/Tk scripting toolkit, and the CORE daemon requires Python. Details of the individual software packages required can be found in the installation steps.
.. _Required_Hardware:
@ -61,7 +61,7 @@ Required Hardware
.. index:: System requirements
Any computer capable of running Linux or FreeBSD should be able to run CORE. Since the physical machine will be hosting numerous virtual machines, as a general rule you should select a machine having as much RAM and CPU resources as possible.
Any computer capable of running Linux should be able to run CORE. Since the physical machine will be hosting numerous virtual machines, as a general rule you should select a machine having as much RAM and CPU resources as possible.
A *general recommendation* would be:
@ -70,9 +70,9 @@ A *general recommendation* would be:
* about 3 MB of free disk space (plus more for dependency packages such as Tcl/Tk)
* X11 for the GUI, or remote X11 over SSH
The computer can be a laptop, desktop, or rack-mount server. A keyboard, mouse,
The computer can be a laptop, desktop, or rack-mount server. A keyboard, mouse,
and monitor are not required if a network connection is available
for remotely accessing the machine. A 3D accelerated graphics card
for remotely accessing the machine. A 3D accelerated graphics card
is not required.
.. _Required_Software:
@ -80,18 +80,13 @@ is not required.
Required Software
-----------------
CORE requires the Linux or FreeBSD operating systems because it uses virtualization provided by the kernel. It does not run on the Windows or Mac OS X operating systems (unless it is running within a virtual machine guest.) There are two
different virtualization technologies that CORE can currently use:
Linux network namespaces and FreeBSD jails,
CORE requires a Linux operating systems because it uses virtualization provided by the kernel. It does not run on the Windows or Mac OS X operating systems (unless it is running within a virtual machine guest.)
The virtualization technology that CORE currently uses:
Linux network namespaces,
see :ref:`How_Does_it_Work?` for virtualization details.
**Linux network namespaces is the recommended platform.** Development is focused here and it supports the latest features. It is the easiest to install because there is no need to patch, install, and run a special Linux kernel.
FreeBSD |BSDVERSION|-RELEASE may offer the best scalability. If your
applications run under FreeBSD and you are comfortable with that platform,
this may be a good choice. Device and application support by BSD
may not be as extensive as Linux.
The CORE GUI requires the X.Org X Window system (X11), or can run over a
remote X11 session. For specific Tcl/Tk, Python, and other libraries required
to run CORE, refer to the :ref:`Installation` section.
@ -113,7 +108,7 @@ Installing from Packages
The easiest way to install CORE is using the pre-built packages. The package
managers on Ubuntu or Fedora will
automatically install dependencies for you.
automatically install dependencies for you.
You can obtain the CORE packages from the `CORE downloads <http://downloads.pf.itd.nrl.navy.mil/core/packages/>`_ page
or `CORE GitHub <https://github.com/coreemu/core/releases>`_.
@ -143,7 +138,7 @@ First install the Ubuntu |UBUNTUVERSION| operating system.
to select which Quagga package to use.
* **Optional:** install the prerequisite packages (otherwise skip this
* **Optional:** install the prerequisite packages (otherwise skip this
step and have the package manager install them for you.)
.. parsed-literal::
@ -152,13 +147,13 @@ First install the Ubuntu |UBUNTUVERSION| operating system.
# update-manager instead of apt-get update/dist-upgrade
sudo apt-get update
sudo apt-get dist-upgrade
sudo apt-get install |APTDEPS| |APTDEPS2|
sudo apt-get install |APTDEPS| |APTDEPS2|
* Install Quagga for routing. If you plan on working with wireless
networks, we recommend
networks, we recommend
installing
`OSPF MDR <http://www.nrl.navy.mil/itd/ncs/products/ospf-manet>`__
(replace `amd64` below with `i386` if needed
(replace `amd64` below with `i386` if needed
to match your architecture):
.. parsed-literal::
@ -172,7 +167,7 @@ First install the Ubuntu |UBUNTUVERSION| operating system.
::
sudo apt-get install quagga
* Install the CORE deb packages for Ubuntu, using a GUI that automatically
resolves dependencies (note that the absolute path to the deb file
must be used with ``software-center``):
@ -181,24 +176,24 @@ First install the Ubuntu |UBUNTUVERSION| operating system.
software-center /home/user/Downloads/core-daemon\_\ |version|-|COREDEB|
software-center /home/user/Downloads/core-gui\_\ |version|-|COREDEB2|
or install from command-line:
.. parsed-literal::
sudo dpkg -i core-daemon\_\ |version|-|COREDEB|
sudo dpkg -i core-gui\_\ |version|-|COREDEB2|
* Start the CORE daemon as root.
::
sudo /etc/init.d/core-daemon start
* Run the CORE GUI as a normal user:
::
core-gui
After running the ``core-gui`` command, a GUI should appear with a canvas
for drawing topologies. Messages will print out on the console about
@ -217,7 +212,7 @@ examples below, replace with `i686` is using a 32-bit architecture. Also,
Fedora release number.
* **CentOS only:** in order to install the `libev` and `tkimg` prerequisite
packages, you
packages, you
first need to install the `EPEL <http://fedoraproject.org/wiki/EPEL>`_ repo
(Extra Packages for Enterprise Linux):
@ -229,7 +224,7 @@ Fedora release number.
* **CentOS 7.x only:** as of this writing, the `tkimg` prerequisite package
is missing from EPEL 7.x, but the EPEL 6.x package can be manually installed
from
from
`here <http://dl.fedoraproject.org/pub/epel/6/x86_64/repoview/tkimg.html>`_
::
@ -249,7 +244,7 @@ Fedora release number.
yum install |YUMDEPS| |YUMDEPS2|
* **Optional (Fedora 17+):** Fedora 17 and newer have an additional
* **Optional (Fedora 17+):** Fedora 17 and newer have an additional
prerequisite providing the required netem kernel modules (otherwise
skip this step and have the package manager install it for you.)
@ -272,7 +267,7 @@ Fedora release number.
::
yum install quagga
* Install the CORE RPM packages for Fedora and automatically resolve
dependencies:
@ -281,14 +276,14 @@ Fedora release number.
yum localinstall python-core_|service|-|version|-|CORERPM| --nogpgcheck
yum localinstall core-gui-|version|-|CORERPM2| --nogpgcheck
or install from the command-line:
.. parsed-literal::
rpm -ivh python-core_|service|-|version|-|CORERPM|
rpm -ivh core-gui-|version|-|CORERPM2|
* Turn off SELINUX by setting ``SELINUX=disabled`` in the :file:`/etc/sysconfig/selinux` file, and adding ``selinux=0`` to the kernel line in
your :file:`/etc/grub.conf` file; on Fedora 15 and newer, disable sandboxd using ``chkconfig sandbox off``;
@ -304,12 +299,12 @@ Fedora release number.
systemctl start core-daemon.service
# or for CentOS:
/etc/init.d/core-daemon start
* Run the CORE GUI as a normal user:
::
core-gui
After running the ``core-gui`` command, a GUI should appear with a canvas
for drawing topologies. Messages will print out on the console about
@ -335,11 +330,11 @@ These packages are not required for normal binary package installs.
sudo apt-get install |APTDEPS| \\
|APTDEPS2| \\
|APTDEPS3|
You can obtain the CORE source from the `CORE source <http://downloads.pf.itd.nrl.navy.mil/core/source/>`_ page. Choose either a stable release version or
the development snapshot available in the `nightly_snapshots` directory.
The ``-j8`` argument to ``make`` will run eight simultaneous jobs, to speed up
the development snapshot available in the `nightly_snapshots` directory.
The ``-j8`` argument to ``make`` will run eight simultaneous jobs, to speed up
builds on multi-core systems.
.. parsed-literal::
@ -350,9 +345,9 @@ builds on multi-core systems.
./configure
make -j8
sudo make install
The CORE Manual documentation is built separately from the :file:`doc/`
The CORE Manual documentation is built separately from the :file:`doc/`
sub-directory in the source. It requires Sphinx:
.. parsed-literal::
@ -376,16 +371,16 @@ These packages are not required for normal binary package installs.
yum install |YUMDEPS| \\
|YUMDEPS2| \\
|YUMDEPS3|
.. NOTE::
For a minimal X11 installation, also try these packages::
yum install xauth xterm urw-fonts
You can obtain the CORE source from the `CORE source <http://downloads.pf.itd.nrl.navy.mil/core/source/>`_ page. Choose either a stable release version or
the development snapshot available in the :file:`nightly_snapshots` directory.
The ``-j8`` argument to ``make`` will run eight simultaneous jobs, to speed up
The ``-j8`` argument to ``make`` will run eight simultaneous jobs, to speed up
builds on multi-core systems. Notice the ``configure`` flag to tell the build
system that a systemd service file should be installed under Fedora.
@ -397,18 +392,12 @@ system that a systemd service file should be installed under Fedora.
./configure --with-startup=systemd
make -j8
sudo make install
Note that the Linux RPM and Debian packages do not use the ``/usr/local``
prefix, and files are instead installed to ``/usr/sbin``, and
``/usr/lib``. This difference is a result of aligning with the directory
structure of Linux packaging systems and FreeBSD ports packaging.
Another note is that the Python distutils in Fedora Linux will install the CORE
Python modules to :file:`/usr/lib/python2.7/site-packages/core`, instead of
using the :file:`dist-packages` directory.
The CORE Manual documentation is built separately from the :file:`doc/`
The CORE Manual documentation is built separately from the :file:`doc/`
sub-directory in the source. It requires Sphinx:
.. parsed-literal::
@ -438,7 +427,7 @@ CentOS/EL6 does not use the systemd service file, so the `configure` option
`--with-startup=systemd` should be omitted:
::
./configure
@ -448,12 +437,12 @@ CentOS/EL6 does not use the systemd service file, so the `configure` option
Installing from Source on SUSE
------------------------------
To build CORE from source on SUSE or OpenSUSE,
To build CORE from source on SUSE or OpenSUSE,
use the similar instructions shown in :ref:`Installing_from_Source_on_Fedora`,
except that the following `configure` option should be used:
::
./configure --with-startup=suse
This causes a separate init script to be installed that is tailored towards SUSE systems.
@ -463,153 +452,6 @@ The `zypper` command is used instead of `yum`.
For OpenSUSE/Xen based installations, refer to the `README-Xen` file included
in the CORE source.
.. _Installing_from_Source_on_FreeBSD:
Installing from Source on FreeBSD
---------------------------------
.. index:: kernel patch
**Rebuilding the FreeBSD Kernel**
The FreeBSD kernel requires a small patch to allow per-node directories in the
filesystem. Also, the `VIMAGE` build option needs to be turned on to enable
jail-based network stack virtualization. The source code for the FreeBSD
kernel is located in :file:`/usr/src/sys`.
Instructions below will use the :file:`/usr/src/sys/amd64` architecture
directory, but the directory :file:`/usr/src/sys/i386` should be substituted
if you are using a 32-bit architecture.
The kernel patch is available from the CORE source tarball under core-|version|/kernel/symlinks-8.1-RELEASE.diff. This patch applies to the
FreeBSD 8.x or 9.x kernels.
.. parsed-literal::
cd /usr/src/sys
# first you can check if the patch applies cleanly using the '-C' option
patch -p1 -C < ~/core-|version|/kernel/symlinks-8.1-RELEASE.diff
# without '-C' applies the patch
patch -p1 < ~/core-|version|/kernel/symlinks-8.1-RELEASE.diff
A kernel configuration file named :file:`CORE` can be found within the source tarball: core-|version|/kernel/freebsd8-config-CORE. The config is valid for
FreeBSD 8.x or 9.x kernels.
The contents of this configuration file are shown below; you can edit it to suit your needs.
::
# this is the FreeBSD 9.x kernel configuration file for CORE
include GENERIC
ident CORE
options VIMAGE
nooptions SCTP
options IPSEC
device crypto
options IPFIREWALL
options IPFIREWALL_DEFAULT_TO_ACCEPT
The kernel configuration file can be linked or copied to the kernel source directory. Use it to configure and build the kernel:
.. parsed-literal::
cd /usr/src/sys/amd64/conf
cp ~/core-|version|/kernel/freebsd8-config-CORE CORE
config CORE
cd ../compile/CORE
make cleandepend && make depend
make -j8 && make install
Change the number 8 above to match the number of CPU cores you have times two.
Note that the ``make install`` step will move your existing kernel to
``/boot/kernel.old`` and removes that directory if it already exists. Reboot to
enable this new patched kernel.
**Building CORE from Source on FreeBSD**
Here are the prerequisite packages from the FreeBSD ports system:
::
pkg_add -r tk85
pkg_add -r libimg
pkg_add -r bash
pkg_add -r libev
pkg_add -r sudo
pkg_add -r python
pkg_add -r autotools
pkg_add -r gmake
Note that if you are installing to a bare FreeBSD system and want to SSH with X11 forwarding to that system, these packages will help:
::
pkg_add -r xauth
pkg_add -r xorg-fonts
The ``sudo`` package needs to be configured so a normal user can run the CORE
GUI using the command ``core-gui`` (opening a shell window on a node uses a
command such as ``sudo vimage n1``.)
On FreeBSD, the CORE source is built using autotools and gmake:
.. parsed-literal::
tar xzf core-|version|.tar.gz
cd core-|version|
./bootstrap.sh
./configure
gmake -j8
sudo gmake install
Build and install the ``vimage`` utility for controlling virtual images. The source can be obtained from `FreeBSD SVN <http://svn.freebsd.org/viewvc/base/head/tools/tools/vimage/>`_, or it is included with the CORE source for convenience:
.. parsed-literal::
cd core-|version|/kernel/vimage
make
make install
.. index:: FreeBSD; kernel modules
.. index:: kernel modules
.. index:: ng_wlan and ng_pipe
On FreeBSD you should also install the CORE kernel modules for wireless emulation. Perform this step after you have recompiled and installed FreeBSD kernel.
.. parsed-literal::
cd core-|version|/kernel/ng_pipe
make
sudo make install
cd ../ng_wlan
make
sudo make install
The :file:`ng_wlan` kernel module allows for the creation of WLAN nodes. This
is a modified :file:`ng_hub` Netgraph module. Instead of packets being copied
to every connected node, the WLAN maintains a hash table of connected node
pairs. Furthermore, link parameters can be specified for node pairs, in
addition to the on/off connectivity. The parameters are tagged to each packet
and sent to the connected :file:`ng_pipe` module. The :file:`ng_pipe` has been
modified to read any tagged parameters and apply them instead of its default
link effects.
The :file:`ng_wlan` also supports linking together multiple WLANs across different machines using the :file:`ng_ksocket` Netgraph node, for distributed emulation.
The Quagga routing suite is recommended for routing,
:ref:`Quagga_Routing_Software` for installation.
@ -624,12 +466,12 @@ Virtual networks generally require some form of routing in order to work (e.g.
to automatically populate routing tables for routing packets from one subnet
to another.) CORE builds OSPF routing protocol
configurations by default when the blue router
node type is used. The OSPF protocol is available
from the `Quagga open source routing suite <http://www.quagga.net>`_.
node type is used. The OSPF protocol is available
from the `Quagga open source routing suite <http://www.quagga.net>`_.
Other routing protocols are available using different
node services, :ref:`Default_Services_and_Node_Types`.
Quagga is not specified as a dependency for the CORE packages because
Quagga is not specified as a dependency for the CORE packages because
there are two different Quagga packages that you may use:
* `Quagga <http://www.quagga.net>`_ - the standard version of Quagga, suitable for static wired networks, and usually available via your distribution's package manager.
@ -639,7 +481,7 @@ there are two different Quagga packages that you may use:
.. index:: MANET Designated Routers (MDR)
*
*
`OSPF MANET Designated Routers <http://www.nrl.navy.mil/itd/ncs/products/ospf-manet>`_ (MDR) - the Quagga routing suite with a modified version of OSPFv3,
optimized for use with mobile wireless networks. The *mdr* node type (and the MDR service) requires this variant of Quagga.
@ -651,26 +493,19 @@ otherwise install the standard version of Quagga using your package manager or f
Installing Quagga from Packages
-------------------------------
To install the standard version of Quagga from packages, use your package
manager (Linux) or the ports system (FreeBSD).
To install the standard version of Quagga from packages, use your package manager (Linux).
Ubuntu users:
::
sudo apt-get install quagga
Fedora users:
::
yum install quagga
FreeBSD users:
::
pkg_add -r quagga
To install the Quagga variant having OSPFv3 MDR, first download the
To install the Quagga variant having OSPFv3 MDR, first download the
appropriate package, and install using the package manager.
Ubuntu users:
@ -709,7 +544,7 @@ To compile Quagga to work with CORE on Linux:
--localstatedir=/var/run/quagga
make
sudo make install
Note that the configuration directory :file:`/usr/local/etc/quagga` shown for
Quagga above could be :file:`/etc/quagga`, if you create a symbolic link from
@ -723,26 +558,9 @@ If you try to run quagga after installing from source and get an error such as:
error while loading shared libraries libzebra.so.0
this is usually a sign that you have to run `sudo ldconfig` to refresh the
this is usually a sign that you have to run `sudo ldconfig` to refresh the
cache file.
To compile Quagga to work with CORE on FreeBSD:
.. parsed-literal::
tar xzf |QVER|.tar.gz
cd |QVER|
./configure --enable-user=root --enable-group=wheel \\
--sysconfdir=/usr/local/etc/quagga --enable-vtysh \\
--localstatedir=/var/run/quagga
gmake
gmake install
On FreeBSD |BSDVERSION| you can use ``make`` or ``gmake``.
You probably want to compile Quagga from the ports system in
:file:`/usr/ports/net/quagga`.
VCORE
=====