docs: updates to install page to cover all install types and PATH issues
This commit is contained in:
parent
4b2d33c898
commit
c067de6792
1 changed files with 160 additions and 141 deletions
301
docs/install.md
301
docs/install.md
|
@ -2,13 +2,16 @@
|
|||
* Table of Contents
|
||||
{: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
|
||||
|
||||
## 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
|
||||
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.
|
||||
|
@ -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.
|
||||
|
||||
Verified:
|
||||
* Ubuntu - 18.04, 20.04
|
||||
* CentOS - 7.8, 8.0
|
||||
|
||||
> **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 |
|
||||
* Ubuntu - 18.04, 20.04, 22.04
|
||||
* CentOS - 7.8
|
||||
|
||||
### 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
|
||||
|
||||
* executable files
|
||||
* `<prefix>/bin/{core-daemon, core-gui, vcmd, vnoded, etc}`
|
||||
* executables
|
||||
* `<prefix>/bin/{vcmd, vnode}`
|
||||
* can be adjusted using script based install , package will be /usr
|
||||
* python files
|
||||
* poetry virtual env
|
||||
* `cd <repo>/daemon && poetry env info`
|
||||
* `~/.cache/pypoetry/virtualenvs/`
|
||||
* local python install
|
||||
* default install path for python3 installation of a wheel
|
||||
* virtual environment `/opt/core/venv`
|
||||
* local install will be local to the python version used
|
||||
* `python3 -c "import core; print(core.__file__)"`
|
||||
* scripts {core-daemon, core-cleanup, etc}
|
||||
* virtualenv `/opt/core/venv/bin`
|
||||
* local `/usr/local/bin`
|
||||
* configuration files
|
||||
* `/etc/core/{core.conf, logging.conf}`
|
||||
* ospf mdr repository files
|
||||
* ospf mdr repository files when using script based install
|
||||
* `<repo>/../ospf-mdr`
|
||||
* emane repository files
|
||||
* `<repo>/../emane`
|
||||
|
||||
### Installed Executables
|
||||
After the installation complete it will have installed the following scripts.
|
||||
### Installed Scripts
|
||||
The following python scripts are provided.
|
||||
|
||||
| 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-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
|
||||
before proceeding to install.
|
||||
|
||||
|
@ -105,72 +85,81 @@ sudo yum 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
|
||||
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,
|
||||
> tk compatibility for python gui, and venv for virtualenvs
|
||||
> **NOTE:** PYTHON defaults to python3 for installs below, CORE requires python3.6+, pip,
|
||||
> tk compatibility for python gui, and venv for virtual environments
|
||||
|
||||
Examples for install:
|
||||
```shell
|
||||
# recommended to upgrade to the latest version of pip before installation
|
||||
# in python, can help avoid building from source issues
|
||||
<python> -m pip install --upgrade pip
|
||||
|
||||
# install core vcmd/vnoded, system dependencies,
|
||||
sudo <python> -m pip install --upgrade pip
|
||||
# install vcmd/vnoded, system dependencies,
|
||||
# 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
|
||||
NO_VENV=1 <yum/apt> install -y ./<package>
|
||||
|
||||
# change python executable used to install for venv and direct installations
|
||||
PYTHON=python3.9 <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
|
||||
sudo PYTHON=python3.9 <yum/apt> install -y ./<package>
|
||||
# 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
|
||||
# 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
|
||||
<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
|
||||
First we will need to clone and navigate to the CORE repo.
|
||||
Example for removal, requires using the same options as install:
|
||||
```shell
|
||||
# clone CORE repo
|
||||
git clone https://github.com/coreemu/core.git
|
||||
cd core
|
||||
# install dependencies to run installation task
|
||||
./setup.sh
|
||||
# run the following or open a new terminal
|
||||
source ~/.bashrc
|
||||
# Ubuntu
|
||||
inv install
|
||||
# CentOS
|
||||
inv install -p /usr
|
||||
# remove a standard install
|
||||
sudo <yum/apt> remove core
|
||||
# remove a local install
|
||||
sudo NO_VENV=1 <yum/apt> remove core
|
||||
# remove install using alternative python
|
||||
sudo PYTHON=python3.9 <yum/apt> remove core
|
||||
# remove install using alternative python and local install
|
||||
sudo NO_VENV=1 PYTHON=python3.9 <yum/apt> remove core
|
||||
# remove install and skip python uninstall
|
||||
sudo NO_PYTHON=1 <yum/apt> remove core
|
||||
```
|
||||
|
||||
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
|
||||
> attempts to install OSs that are debian/redhat like (yum/apt).
|
||||
```shell
|
||||
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
|
||||
* pipx 0.16.4 via pip
|
||||
* invoke 1.4.1 via pipx
|
||||
* poetry 1.1.12 via pipx
|
||||
When done see [Post Install](#post-install).
|
||||
|
||||
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
|
||||
* builds vcmd/vnoded and python grpc files
|
||||
* 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
|
||||
* 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,
|
||||
> if the default prefix /usr/local will not be valid
|
||||
|
||||
```shell
|
||||
inv -h install
|
||||
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 |
|
||||
|
||||
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 ...]
|
||||
|
||||
Docstring:
|
||||
|
@ -192,45 +211,13 @@ Options:
|
|||
-d, --dev install development mode
|
||||
-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
|
||||
-n, --no-python avoid installing python system dependencies
|
||||
-o, --[no-]ospf disable ospf installation
|
||||
-p STRING, --prefix=STRING prefix where scripts are installed, default is /usr/local
|
||||
-v, --verbose enable verbose
|
||||
|
||||
# install core to virtual environment
|
||||
./install.sh -p <prefix>
|
||||
|
||||
# install core locally
|
||||
./install.sh -p <prefix> -l
|
||||
-v, --verbose
|
||||
```
|
||||
|
||||
After installation has completed you should be able to run `core-daemon` and `core-gui`.
|
||||
|
||||
## 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
|
||||
```
|
||||
When done see [Post Install](#post-install).
|
||||
|
||||
### Unsupported Linux Distribution
|
||||
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>
|
||||
```
|
||||
|
||||
## Dockerfile Install
|
||||
You can leverage the provided Dockerfile, to run and launch CORE within a Docker container.
|
||||
## Dockerfile Based Install
|
||||
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
|
||||
# clone core
|
||||
git clone https://github.com/coreemu/core.git
|
||||
cd core
|
||||
# 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
|
||||
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
|
||||
xhost +local:root
|
||||
# launch core-gui
|
||||
sudo docker exec -it core core-gui
|
||||
```
|
||||
|
||||
## Running User Scripts
|
||||
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>
|
||||
```
|
||||
When done see [Post Install](#post-install).
|
||||
|
||||
## Installing EMANE
|
||||
> **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
|
||||
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
|
||||
```
|
||||
|
|
Loading…
Reference in a new issue