From 0a10b41418a0fa6922fc2e18e7332c4245817e39 Mon Sep 17 00:00:00 2001 From: grossmj Date: Sun, 13 Mar 2022 15:44:26 +1030 Subject: [PATCH] Convert README to markdown --- README.md | 165 +++++++++++++++++++++++++++++++++++ README.rst | 246 ----------------------------------------------------- 2 files changed, 165 insertions(+), 246 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 00000000..68946f93 --- /dev/null +++ b/README.md @@ -0,0 +1,165 @@ +# GNS3-server + +[![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. +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 + +In addition to Python dependencies listed in a section below, 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 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. + +### Docker support + +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). + +## 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. + +## Linux + +GNS3 is perhaps packaged for your distribution: + +* [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) + + +### Linux (Debian based) + +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: + +```shell +sudo apt-get install python3-setuptools +``` + +Finally, these commands will install the server as well as the rest of the dependencies: + +```shell +cd gns3-server-master +python3 -m venv venv-gns3server +source venv-gns3server/bin/activate +sudo python3 setup.py install +python3 -m gns3server --local +``` + +To run tests use: + +```shell +python3 -m pytest tests +``` + +## Docker container + +For development, 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 + +```shell +python3 -m pip install -r dev-requirements.txt +``` + +Then run the tests using pytest + +```shell +python3 -m pytest -vv tests/ +``` + +## Security issues + +Please contact us at security@gns3.net diff --git a/README.rst b/README.rst deleted file mode 100644 index 227dea53..00000000 --- a/README.rst +++ /dev/null @@ -1,246 +0,0 @@ -GNS3-server -=========== - -.. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://github.com/psf/black - -.. image:: https://github.com/GNS3/gns3-server/workflows/testing/badge.svg?branch=3.0 - :target: https://github.com/GNS3/gns3-server/actions?query=workflow%3Atesting+branch%3A3.0 - -.. image:: https://img.shields.io/pypi/v/gns3-server.svg - :target: https://pypi.python.org/pypi/gns3-server - -.. image:: https://snyk.io/test/github/GNS3/gns3-server/badge.svg - :target: 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. -Clients like the `GNS3 GUI `_ and the `GNS3 Web UI `_ control the server using a HTTP REST API. - -Software dependencies ---------------------- - -In addition of Python dependencies listed in a section below, other software may be required, recommended or optional. - -* `uBridge `_ is required, it interconnects the nodes. -* `Dynamips `_ is required for running IOS routers (using real IOS images) as well as the internal switches and hubs. -* `VPCS `_ is recommended, it is a builtin node simulating a very simple computer to perform connectitivy 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. - -Docker support -************** - -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). - -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. - -2.x (2.3 for example) -********************* -Next major release - -*Never* use this branch for production. Pull requests for major new features go here. - -Linux ------ - -GNS3 is perhaps packaged for your distribution: - -* 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 - - -Linux (Debian based) --------------------- - -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 `here `_ - -The following commands will install some of these dependencies: - -.. code:: bash - - sudo apt-get install python3-setuptools - -Finally these commands will install the server as well as the rest of the dependencies: - -.. code:: bash - - cd gns3-server-master - python3 -m venv venv-gns3server - source venv-gns3server/bin/activate - sudo python3 setup.py install - python3 -m gns3server --local - -To run tests use: - -.. code:: bash - - python3 -m pytest tests - - -Docker container -**************** - -For development you can run the GNS3 server in a container - -.. code:: bash - - bash scripts/docker_dev_server.sh - - -Run as daemon (Unix only) -************************** - -You will find init sample scripts for various systems -inside the init directory. - -Usefull 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. - -.. code:: bash - - sudo adduser gns3 - -upstart -------- - -For ubuntu < 15.04 - -You need to copy init/gns3.conf.upstart to /etc/init/gns3.conf - -.. code:: bash - - sudo chown root /etc/init/gns3.conf - sudo service gns3 start - - -systemd -------- - -You need to copy init/gns3.service.systemd to /lib/systemd/system/gns3.service - -.. code:: bash - - sudo chown root /lib/systemd/system/gns3.service - sudo systemctl start gns3 - -Windows -------- - - -Please use our `all-in-one installer `_ to install the stable build. - -If you install via source you need to first install: - -- Python (3.3 or above) - https://www.python.org/downloads/windows/ -- Pywin32 - https://sourceforge.net/projects/pywin32/ - -Then you can call - -.. code:: bash - - python setup.py install - -to install the remaining dependencies. - -To run the tests, you also need to call - -.. code:: bash - - pip install pytest pytest-capturelog - -before actually running the tests with - -.. code:: bash - - python setup.py test - -or with - -.. code:: bash - - py.test -v - -Mac OS X --------- - -Please use our DMG package for a simple installation. - -If you want to test the current git version or contribute to the project, -you can follow these instructions with virtualenwrapper: http://virtualenvwrapper.readthedocs.org/ -and homebrew: http://brew.sh/. - -.. code:: bash - - brew install python3 - mkvirtualenv gns3-server --python=/usr/local/bin/python3.5 - python3 setup.py install - gns3server - -SSL ---- - -If you want enable SSL support on GNS3 you can generate a self signed certificate: - -.. code:: bash - - 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: - -.. code:: bash - - 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: - -.. code:: ini - - [Server] - certfile=/Users/noplay/.config/GNS3/ssl/server.cert - certkey=/Users/noplay/.config/GNS3/ssl/server.key - ssl=True - -Running tests -************* - -Just run: - -.. code:: bash - - py.test -vv - -If you want test coverage: - -.. code:: bash - - py.test --cov-report term-missing --cov=gns3server - -Security issues ----------------- -Please contact us using contact form available here: -http://docs.gns3.com/1ON9JBXSeR7Nt2-Qum2o3ZX0GU86BZwlmNSUgvmqNWGY/index.html