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

docs: updates to install page to cover all install types and PATH issues

Browse source
This commit is contained in:
Blake Harnden 2022-10-07 12:52:53 -07:00
parent 4b2d33c898
commit c067de6792
1 changed files with 160 additions and 141 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

301
docs/install.md
View file

@ -2,13 +2,16 @@
* Table of Contents * Table of Contents
{:toc} {:toc}
## Overview
CORE provides a script to help automate the installation of dependencies,
build and install, and either generate a CORE specific python virtual environment
or build and install a python wheel.
> **WARNING:** if Docker is installed, the default iptable rules will block CORE traffic > **WARNING:** if Docker is installed, the default iptable rules will block CORE traffic
## Overview
CORE currently supports and provides the following install options, with the package
option being preferred.
* [Package based install (rpm/deb)](#package-based-install)
* [Script based install](#script-based-install)
* [Dockerfile based install](#dockerfile-based-install)
### Requirements ### Requirements
Any computer capable of running Linux should be able to run CORE. Since the physical machine will be hosting numerous Any computer capable of running Linux should be able to run CORE. Since the physical machine will be hosting numerous
containers, as a general rule you should select a machine having as much RAM and CPU resources as possible. containers, as a general rule you should select a machine having as much RAM and CPU resources as possible.
@ -21,52 +24,29 @@ containers, as a general rule you should select a machine having as much RAM and
Plan is to support recent Ubuntu and CentOS LTS releases. Plan is to support recent Ubuntu and CentOS LTS releases.
Verified: Verified:
* Ubuntu - 18.04, 20.04 * Ubuntu - 18.04, 20.04, 22.04
* CentOS - 7.8, 8.0 * CentOS - 7.8
> **NOTE:** CentOS 8 does not have the netem kernel mod available by default
CentOS 8 Enabled netem:
```shell
sudo yum update
# restart into updated kernel
sudo yum install -y kernel-modules-extra
sudo modprobe sch_netem
```
### Tools Used
The following tools will be leveraged during installation:
| Tool | Description |
|---------------------------------------------|-----------------------------------------------------------------------|
| [pip](https://pip.pypa.io/en/stable/) | used to install pipx |
| [pipx](https://pipxproject.github.io/pipx/) | used to install standalone python tools (invoke, poetry) |
| [invoke](http://www.pyinvoke.org/) | used to run provided tasks (install, uninstall, reinstall, etc) |
| [poetry](https://python-poetry.org/) | used to install python virtual environment or building a python wheel |
### Files ### Files
The following is a list of files that would be installed after running the automated installation. The following is a list of files that would be installed after installation.
> **NOTE:** the default install prefix is /usr/local, but can be changed as noted below * executables
* `<prefix>/bin/{vcmd, vnode}`
* executable files * can be adjusted using script based install , package will be /usr
* `<prefix>/bin/{core-daemon, core-gui, vcmd, vnoded, etc}`
* python files * python files
* poetry virtual env * virtual environment `/opt/core/venv`
* `cd <repo>/daemon && poetry env info` * local install will be local to the python version used
* `~/.cache/pypoetry/virtualenvs/`
* local python install
* default install path for python3 installation of a wheel
* `python3 -c "import core; print(core.__file__)"` * `python3 -c "import core; print(core.__file__)"`
* scripts {core-daemon, core-cleanup, etc}
* virtualenv `/opt/core/venv/bin`
* local `/usr/local/bin`
* configuration files * configuration files
* `/etc/core/{core.conf, logging.conf}` * `/etc/core/{core.conf, logging.conf}`
* ospf mdr repository files * ospf mdr repository files when using script based install
* `<repo>/../ospf-mdr` * `<repo>/../ospf-mdr`
* emane repository files
* `<repo>/../emane`
### Installed Executables ### Installed Scripts
After the installation complete it will have installed the following scripts. The following python scripts are provided.
| Name | Description | | Name | Description |
|---------------------|------------------------------------------------------------------------------| |---------------------|------------------------------------------------------------------------------|
@ -78,7 +58,7 @@ After the installation complete it will have installed the following scripts.
| core-route-monitor | tool to help monitor traffic across nodes and feed that to SDT | | core-route-monitor | tool to help monitor traffic across nodes and feed that to SDT |
| core-service-update | tool to update automate modifying a legacy service to match current naming | | core-service-update | tool to update automate modifying a legacy service to match current naming |
## Upgrading from Older Release ### Upgrading from Older Release
Please make sure to uninstall any previous installations of CORE cleanly Please make sure to uninstall any previous installations of CORE cleanly
before proceeding to install. before proceeding to install.
@ -105,72 +85,81 @@ sudo yum remove core
sudo apt remove core sudo apt remove core
``` ```
## Installing from Packages ## Package Based Install
Starting with 9.0.0 there are pre-built rpm/deb packages. You can retrieve the Starting with 9.0.0 there are pre-built rpm/deb packages. You can retrieve the
rpm/deb package from [releases](https://github.com/coreemu/core/releases) page. rpm/deb package from [releases](https://github.com/coreemu/core/releases) page.
> **NOTE:** PYTHON defaults to python3 for installs below The built packages will require and install system level dependencies, as well as running
a post install script to install the provided CORE python wheel. A similar uninstall script
is ran when uninstalling and would require the same options as given, during the install.
> **NOTE:** the python install requires python3.6+, pip, > **NOTE:** PYTHON defaults to python3 for installs below, CORE requires python3.6+, pip,
> tk compatibility for python gui, and venv for virtualenvs > tk compatibility for python gui, and venv for virtual environments
Examples for install:
```shell ```shell
# recommended to upgrade to the latest version of pip before installation # recommended to upgrade to the latest version of pip before installation
# in python, can help avoid building from source issues # in python, can help avoid building from source issues
<python> -m pip install --upgrade pip sudo <python> -m pip install --upgrade pip
# install vcmd/vnoded, system dependencies,
# install core vcmd/vnoded, system dependencies,
# and core python into a venv located at /opt/core/venv # and core python into a venv located at /opt/core/venv
<yum/apt> install -y ./<package> sudo <yum/apt> install -y ./<package>
# disable the venv and install to python directly # disable the venv and install to python directly
NO_VENV=1 <yum/apt> install -y ./<package> sudo NO_VENV=1 <yum/apt> install -y ./<package>
# change python executable used to install for venv or direct installations
# change python executable used to install for venv and direct installations sudo PYTHON=python3.9 <yum/apt> install -y ./<package>
PYTHON=python3.9 <yum/apt> install -y ./<package>
# disable venv and change python executable # disable venv and change python executable
NO_VENV=1 PYTHON=python3.9 <yum/apt> install -y ./<package> sudo NO_VENV=1 PYTHON=python3.9 <yum/apt> install -y ./<package>
# skip installing the python portion entirely, as you plan to carry this out yourself # skip installing the python portion entirely, as you plan to carry this out yourself
# core python wheel is located at /opt/core/core-<version>-py3-none-any.whl # core python wheel is located at /opt/core/core-<version>-py3-none-any.whl
NO_PYTHON=1 <yum/apt> install -y ./<package> sudo NO_PYTHON=1 <yum/apt> install -y ./<package>
# install python wheel into python of your choosing # install python wheel into python of your choosing
<python> -m pip install /opt/core/core-<version>-py3-none-any.whl sudo <python> -m pip install /opt/core/core-<version>-py3-none-any.whl
``` ```
## Automated Install Example for removal, requires using the same options as install:
First we will need to clone and navigate to the CORE repo.
```shell ```shell
# clone CORE repo # remove a standard install
git clone https://github.com/coreemu/core.git sudo <yum/apt> remove core
cd core # remove a local install
# install dependencies to run installation task sudo NO_VENV=1 <yum/apt> remove core
./setup.sh # remove install using alternative python
# run the following or open a new terminal sudo PYTHON=python3.9 <yum/apt> remove core
source ~/.bashrc # remove install using alternative python and local install
# Ubuntu sudo NO_VENV=1 PYTHON=python3.9 <yum/apt> remove core
inv install # remove install and skip python uninstall
# CentOS sudo NO_PYTHON=1 <yum/apt> remove core
inv install -p /usr
``` ```
First you can use `setup.sh` as a convenience to install tooling for running invoke tasks: ### Installing OSPF MDR
You will need to manually install OSPF MDR for routing nodes, since this is not
provided by the package.
> **NOTE:** `setup.sh` will attempt to determine your OS by way of `/etc/os-release`, currently it supports ```shell
> attempts to install OSs that are debian/redhat like (yum/apt). git clone https://github.com/USNavalResearchLaboratory/ospf-mdr.git
cd ospf-mdr
./bootstrap.sh
./configure --disable-doc --enable-user=root --enable-group=root \
--with-cflags=-ggdb --sysconfdir=/usr/local/etc/quagga --enable-vtysh \
--localstatedir=/var/run/quagga
make -j$(nproc)
sudo make install
```
* python3, pip, venv When done see [Post Install](#post-install).
* pipx 0.16.4 via pip
* invoke 1.4.1 via pipx
* poetry 1.1.12 via pipx
Then you can run `inv install <options>`: ## Script Based Install
The script based installation will install system level dependencies, python library and
dependencies, as well as dependencies for building CORE.
The script based install also automatically builds and installs OSPF MDR, used by default
on routing nodes. This can optionally be skipped.
Installaion will carry out the following steps:
* installs system dependencies for building core * installs system dependencies for building core
* builds vcmd/vnoded and python grpc files
* installs core into poetry managed virtual environment or locally, if flag is passed * installs core into poetry managed virtual environment or locally, if flag is passed
* installs scripts pointing to appropriate python location based on install type
* installs systemd service pointing to appropriate python location based on install type * installs systemd service pointing to appropriate python location based on install type
* clone/build/install working version of [OPSF MDR](https://github.com/USNavalResearchLaboratory/ospf-mdr) * clone/build/install working version of [OPSF MDR](https://github.com/USNavalResearchLaboratory/ospf-mdr)
@ -180,9 +169,39 @@ Then you can run `inv install <options>`:
> **NOTE:** provide a prefix that will be found on path when running as sudo, > **NOTE:** provide a prefix that will be found on path when running as sudo,
> if the default prefix /usr/local will not be valid > if the default prefix /usr/local will not be valid
```shell The following tools will be leveraged during installation:
inv -h install
| Tool | Description |
|---------------------------------------------|-----------------------------------------------------------------------|
| [pip](https://pip.pypa.io/en/stable/) | used to install pipx |
| [pipx](https://pipxproject.github.io/pipx/) | used to install standalone python tools (invoke, poetry) |
| [invoke](http://www.pyinvoke.org/) | used to run provided tasks (install, uninstall, reinstall, etc) |
| [poetry](https://python-poetry.org/) | used to install python virtual environment or building a python wheel |
First we will need to clone and navigate to the CORE repo.
```shell
# clone CORE repo
git clone https://github.com/coreemu/core.git
cd core
# install dependencies to run installation task
./setup.sh
# skip installing system packages, due to using python built from source
NO_SYSTEM=1 ./setup.sh
# run the following or open a new terminal
source ~/.bashrc
# Ubuntu
inv install
# CentOS
inv install -p /usr
# optionally skip python system packages
inv install --no-python
# optionally skip installing ospf mdr
inv install --no-ospf
# install command options
Usage: inv[oke] [--core-opts] install [--options] [other tasks here ...] Usage: inv[oke] [--core-opts] install [--options] [other tasks here ...]
Docstring: Docstring:
@ -192,45 +211,13 @@ Options:
-d, --dev install development mode -d, --dev install development mode
-i STRING, --install-type=STRING used to force an install type, can be one of the following (redhat, debian) -i STRING, --install-type=STRING used to force an install type, can be one of the following (redhat, debian)
-l, --local determines if core will install to local system, default is False -l, --local determines if core will install to local system, default is False
-n, --no-python avoid installing python system dependencies
-o, --[no-]ospf disable ospf installation -o, --[no-]ospf disable ospf installation
-p STRING, --prefix=STRING prefix where scripts are installed, default is /usr/local -p STRING, --prefix=STRING prefix where scripts are installed, default is /usr/local
-v, --verbose enable verbose -v, --verbose
# install core to virtual environment
./install.sh -p <prefix>
# install core locally
./install.sh -p <prefix> -l
``` ```
After installation has completed you should be able to run `core-daemon` and `core-gui`. When done see [Post Install](#post-install).
## Using Invoke Tasks
The invoke tool installed by way of pipx provides conveniences for running
CORE tasks to help ensure usage of the create python virtual environment.
```shell
inv --list
Available tasks:
install install core, poetry, scripts, service, and ospf mdr
install-emane install emane python bindings into the core virtual environment
reinstall run the uninstall task, get latest from specified branch, and run install task
test run core tests
test-emane run core emane tests
test-mock run core tests using mock to avoid running as sudo
uninstall uninstall core, scripts, service, virtual environment, and clean build directory
```
### Enabling Service
After installation, the core service is not enabled by default. If you desire to use the
service, run the following commands.
```shell
sudo systemctl enable core-daemon
sudo systemctl start core-daemon
```
### Unsupported Linux Distribution ### Unsupported Linux Distribution
For unsupported OSs you could attempt to do the following to translate For unsupported OSs you could attempt to do the following to translate
@ -246,39 +233,27 @@ an installation to your use case.
inv install --dry -v -p <prefix> -i <install type> inv install --dry -v -p <prefix> -i <install type>
``` ```
## Dockerfile Install ## Dockerfile Based Install
You can leverage the provided Dockerfile, to run and launch CORE within a Docker container. You can leverage one of the provided Dockerfiles, to run and launch CORE within a Docker container.
Since CORE nodes will leverage software available within the system for a given use case,
make sure to update and build the Dockerfile with desired software.
```shell ```shell
# clone core # clone core
git clone https://github.com/coreemu/core.git git clone https://github.com/coreemu/core.git
cd core cd core
# build image # build image
sudo docker build -t core.<cenots,ubuntu> -f Dockerfile.<centos,ubuntu> . sudo docker build -t core -f Dockerfile.<centos,ubuntu,oracle> .
# start container # start container
sudo docker run -itd --name core -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix:rw --privileged core.<centos,ubuntu> sudo docker run -itd --name core -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix:rw --privileged core
# enable xhost access to the root user # enable xhost access to the root user
xhost +local:root xhost +local:root
# launch core-gui # launch core-gui
sudo docker exec -it core core-gui sudo docker exec -it core core-gui
``` ```
## Running User Scripts When done see [Post Install](#post-install).
If you create your own python scripts to run CORE directly or using the gRPC
APIs you will need to make sure you are running them within context of the
installed virtual environment. To help support this CORE provides the `core-python`
executable. This executable will allow you to enter CORE's python virtual
environment interpreter or to run a script within it.
For installations installed to a virtual environment:
```shell
core-python <script>
```
For local installations:
```shell
python3 <script>
```
## Installing EMANE ## Installing EMANE
> **NOTE:** installing EMANE for the virtual environment is known to work for 1.21+ > **NOTE:** installing EMANE for the virtual environment is known to work for 1.21+
@ -295,3 +270,47 @@ cd <CORE_REPO>
# example version tag v1.3.3 # example version tag v1.3.3
inv install-emane -e <emane version tag> inv install-emane -e <emane version tag>
``` ```
## Post Install
After installation completes you are now ready to run CORE.
### Resolving Path Issues
One problem running CORE you may run into, using the virtual environment or locally
can be issues related to your path.
To add support for your user to run scripts from the virtual environment:
```shell
# can add to ~/.bashrc
export PATH=$PATH:/opt/core/venv/bin
```
This will not solve the path issue when running as sudo, so you can do either
of the following to compensate.
```shell
# run command passing in the right PATH to pickup from the user running the command
sudo env PATH=$PATH core-daemon
# add an alias to ~/.bashrc or something similar
alias sudop='sudo env PATH=$PATH'
# now you can run commands like so
sudop core-daemon
```
### Running CORE
The following assumes I have resolved PATH issues and setup the `sudop` alias.
```shell
# in one terminal run the server daemon using the alias above
sudop core-daemon
# in another terminal run the gui client
core-gui
```
### Enabling Service
After installation, the core service is not enabled by default. If you desire to use the
service, run the following commands.
```shell
sudo systemctl enable core-daemon
sudo systemctl start core-daemon
```