mirror of
https://github.com/GNS3/gns3-server
synced 2024-12-30 18:50:58 +00:00
Convert README to markdown
This commit is contained in:
grossmj
parent
f8a83e7ff9
commit
0a10b41418
165
README.md
Normal file
165
README.md
Normal file
@ -0,0 +1,165 @@
|
||||
# GNS3-server
|
||||
|
||||
[](https://github.com/psf/black)
|
||||
[](https://github.com/GNS3/gns3-server/actions?query=workflow%3Atesting+branch%3A3.0)
|
||||
[](https://pypi.python.org/pypi/gns3-server)
|
||||
[](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
|
||||
246
README.rst
246
README.rst
@ -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 <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 of 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 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 <https://github.com/GNS3/gns3-server/blob/master/requirements.txt>`_
|
||||
|
||||
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 <https://community.gns3.com/software/download>`_ 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
|
||||
Loading…
Reference in New Issue
Block a user