From 3edfa53e9e8351c1d96fa4929f5d49af9874893e Mon Sep 17 00:00:00 2001 From: grossmj Date: Mon, 14 Mar 2022 14:46:29 +1030 Subject: [PATCH] Update README.md --- README.md | 187 +++++++++++++++++++++++------------------------------- 1 file changed, 78 insertions(+), 109 deletions(-) diff --git a/README.md b/README.md index 68946f93..b12ddd1f 100644 --- a/README.md +++ b/README.md @@ -1,165 +1,134 @@ -# GNS3-server +# GNS3 server repository [![Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![GitHub Actions tests](https://github.com/GNS3/gns3-server/workflows/testing/badge.svg?branch=3.0)](https://github.com/GNS3/gns3-server/actions?query=workflow%3Atesting+branch%3A3.0) [![Latest PyPi version](https://img.shields.io/pypi/v/gns3-server.svg)](https://pypi.python.org/pypi/gns3-server) [![Snyk scanning](https://snyk.io/test/github/GNS3/gns3-server/badge.svg)](https://snyk.io/test/github/GNS3/gns3-server) -This is the GNS3 server repository. - -The GNS3 server manages emulators such as Dynamips, VirtualBox or Qemu/KVM. +The GNS3 server manages emulators and other virtualization software such as Dynamips, Qemu/KVM, Docker, VPCS, VirtualBox and VMware Workstation. Clients like the [GNS3 GUI](https://github.com/GNS3/gns3-gui/) and the [GNS3 Web UI](https://github.com/GNS3/gns3-web-ui>) control the server using a HTTP REST API. -## Software dependencies +## Installation -In addition to Python dependencies listed in a section below, other software may be required, recommended or optional. +These instructions are for using GNS3, please see below for development. -* [uBridge](https://github.com/GNS3/ubridge/) is required, it interconnects the nodes. -* [Dynamips](https://github.com/GNS3/dynamips/) is required for running IOS routers (using real IOS images) as well as the internal switches and hubs. -* [VPCS](https://github.com/GNS3/vpcs/) is recommended, it is a builtin node simulating a very simple computer to perform connectivity tests using ping, traceroute etc. -* Qemu is strongly recommended on Linux, as most node types are based on Qemu, for example Cisco IOSv and Arista vEOS. -* libvirt is recommended (Linux only), as it's needed for the NAT cloud. -* Docker is optional (Linux only), some nodes are based on Docker. -* mtools is recommended to support data transfer to/from QEMU VMs using virtual disks. -* i386-libraries of libc and libcrypto are optional (Linux only), they are only needed to run IOU based nodes. +### Windows & macOS -### Docker support +Please use our [Windows installer or DMG package](https://gns3.com/software/download) to install the stable build along with the GNS3 VM. +Note that as of GNS3 version above 3.0, you must run the server using the GNS3 VM or on a Linux system (remote, cloud or virtual machine). -Docker support needs the script program (`bsdutils` or `util-linux` package), when running a docker VM and a static busybox during installation (python3 setup.py install / pip3 install / package creation). +### Linux -## Branches +#### Ubuntu based distributions -### master +We build and test packages for actively supported Ubuntu versions. +Other distros based on Ubuntu, like Mint, should also be supported. -master is the next stable release, you can test it in your day-to -day activities. -Bug fixes or small improvements pull requests go here. +Packages can be installed from our Personal Package Archives (PPA) repository: -3.x -Development brand for the next major release +```shell +sudo apt update +sudo apt install software-properties-common +sudo add-apt-repository ppa:gns3/ppa +sudo apt update +sudo apt install gns3-gui gns3-server +``` -**Never** use this branch for production. Pull requests for major new features go here. +#### Other Linux distributions -## Linux - -GNS3 is perhaps packaged for your distribution: +GNS3 is often packaged for other distributions by third-parties: * [Gentoo](https://packages.gentoo.org/package/net-misc/gns3-server) * [Alpine](https://pkgs.alpinelinux.org/package/v3.10/community/x86_64/gns3-server) * [NixOS](https://search.nixos.org/packages?channel=21.11&from=0&size=50&sort=relevance&type=packages&query=gns3-server) +#### PyPi -### Linux (Debian based) +You may use PyPi in case no package is provided, or you would like to do a manual installation: -The following instructions have been tested with Ubuntu and Mint. -You must be connected to the Internet in order to install the dependencies. - -### Dependencies: - -- Python >= 3.6, setuptools and the ones listed in [requirements.txt](https://github.com/GNS3/gns3-server/blob/3.0/requirements.txt>) - -The following commands will install some of these dependencies: +* https://pypi.org/project/gns3-server/ +* https://pypi.org/project/gns3-gui/ ```shell -sudo apt-get install python3-setuptools +python3 -m pip install gns3-gui +python3 -m pip install gns3-server ``` -Finally, these commands will install the server as well as the rest of the dependencies: +The downside of this method is you will have to manually install all dependencies (see below). + +Please see our [documentation](https://docs.gns3.com/docs/getting-started/installation/linux) for more details. + +### Software dependencies + +In addition to Python dependencies, other software may be required, recommended or optional. + +* [uBridge](https://github.com/GNS3/ubridge/) is required, it interconnects the nodes. +* [Dynamips](https://github.com/GNS3/dynamips/) is required for running IOS routers (using real IOS images) as well as the internal switches and hubs. +* [VPCS](https://github.com/GNS3/vpcs/) is recommended, it is a builtin node simulating a very simple computer to perform connectivity tests using ping, traceroute etc. +* Qemu is strongly recommended as most node types are based on Qemu, for example Cisco IOSv and Arista vEOS. +* libvirt is recommended as it's needed for the NAT cloud. +* Docker is optional, some nodes are based on Docker. +* mtools is recommended to support data transfer to/from QEMU VMs using virtual disks. +* i386-libraries of libc and libcrypto are optional, they are only needed to run IOU based nodes. + +Note that Docker needs the script program (`bsdutils` or `util-linux` package), when running a Docker VM and a static busybox during installation (python3 setup.py install / pip3 install / package creation). + +## Development + +### Setting up + +These commands will install the server as well as all Python dependencies: ```shell -cd gns3-server-master +git clone https://github.com/GNS3/gns3-server +cd gns3-server +git checkout 3.0 python3 -m venv venv-gns3server source venv-gns3server/bin/activate -sudo python3 setup.py install +python3 setup.py install python3 -m gns3server --local ``` -To run tests use: +You will have to manually install other software dependencies (see above), for Dynamips, VPCS and uBridge the easiest is to install from our PPA. -```shell -python3 -m pytest tests -``` +### Docker container -## Docker container - -For development, you can run the GNS3 server in a container +Alternatively, you can run the GNS3 server in a container ```shell bash scripts/docker_dev_server.sh ``` -## Run as daemon (Unix only) - -You will find init sample scripts for various systems -inside the init directory. - -Useful options: - -* `--daemon`: start process as a daemon -* `--log logfile`: store output in a logfile -* `--pid pidfile`: store the pid of the running process in a file and prevent double execution - -All init scripts require the creation of a GNS3 user. You can change it to another user. - -```shell -sudo adduser gns3 -``` - -### systemd - -You need to copy init/gns3.service.systemd to /lib/systemd/system/gns3.service - -```shell -sudo chown root /lib/systemd/system/gns3.service -sudo systemctl start gns3 -``` - -## Windows - -Please use our [Windows installer](https://community.gns3.com/software/download) to install the stable build along with the GNS3 VM - -### Mac OS X - -Please use our [DMG package](https://community.gns3.com/software/download) for a simple installation along with the GNS3 VM (VMware Fusion is recommended) - -## SSL - -If you want enable SSL support on GNS3 you can generate a self-signed certificate: - -```shell -bash gns3server/cert_utils/create_cert.sh -``` - -This command will put the files in ~/.config/GNS3/ssl - -After you can start the server in SSL mode with: - -```shell -python gns3server/main.py --certfile ~/.config/GNS3/ssl/server.cert --certkey ~/.config/GNS3/ssl/server.key --ssl -``` - -Or in your gns3_server.conf by adding in the Server section: - -```ini -[Server] -certfile=/Users/noplay/.config/GNS3/ssl/server.cert -certkey=/Users/noplay/.config/GNS3/ssl/server.key -ssl=True -``` - ### Running tests -First, install the development dependencies +First, install the development dependencies: ```shell python3 -m pip install -r dev-requirements.txt ``` -Then run the tests using pytest +Then run the tests using pytest: ```shell python3 -m pytest -vv tests/ ``` -## Security issues +### API documentation -Please contact us at security@gns3.net +The API documentation can be accessed when running the server locally: + +* On `http://IP:PORT/docs` to see with Swagger UI (i.e. `http://localhost:3080/docs`) +* On `http://IP:PORT/redoc` to see with ReDoc (i.e. `http://localhost:3080/redoc`) + +The documentation can also be viewed [online](http://apiv3.gns3.net) however it may not be the most up-to-date version since it needs manually synchronization with the current code. Also, you cannot use this to interact with a GNS3 server. + +### Branches + +#### master + +master is the next stable release, you can test it in your day-to -day activities. +Bug fixes or small improvements pull requests go here. + +3.x development brand for the next major release. + +**Never** use this branch for production. Pull requests for major new features go here. \ No newline at end of file