From ac41e94e96a7a148f765fe0effc2100642a8ec92 Mon Sep 17 00:00:00 2001 From: Paul Rock Date: Sat, 17 Feb 2024 10:54:41 +0300 Subject: [PATCH] Readme updated --- README.md | 145 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 80 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 1013d16..eed1e40 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,64 @@ # Mikrotik RouterOS in Docker -This extrasmall image was created for tests purpose only, for example on -this project based unit testing of [routeros-api-php](https://github.com/EvilFreelancer/routeros-api-php) library. -If you need fully functional "RouterOS in Docker" for production usage -look at [VR Network Lab](https://github.com/plajjan/vrnetlab) project. +This project comprises a Docker image that runs a MikroTik's RouterOS +virtual machine inside QEMU. -## How to use +It's designed to simulate MikroTik's RouterOS environment, making it an +excellent tool for development and testing purposes, especially for those +working with the RouterOS API. -### Create your own `Dockerfile` +This Docker image is particularly useful for unit testing the +[routeros-api-php](https://github.com/EvilFreelancer/routeros-api-php) library, allowing developers to test applications +in a controlled environment that closely mimics a real RouterOS setup. -List of all available tags is [here](https://hub.docker.com/r/evilfreelancer/docker-routeros/tags/), -`latest` will be used by default. +For users seeking a fully operational RouterOS environment for production +use within Docker, the [VR Network Lab](https://github.com/plajjan/vrnetlab) project is recommended +as an alternative. + +## Getting Started + +### Pulling the Image from Docker Hub + +To use the image directly from Docker Hub, you can pull it and run a +container as shown below. This will start a RouterOS instance with ports +configured for SSH, API, API-SSL, and VNC access. + +```bash +docker pull evilfreelancer/docker-routeros +docker run -d -p 2222:22 -p 8728:8728 -p 8729:8729 -p 5900:5900 -ti evilfreelancer/docker-routeros +``` + +### Use in `docker-compose.yml` + +For those preferring docker-compose, an example configuration is provided +below. More examples is [here](docker-compose.dist.yml). + +```yml +version: "3.9" +services: + routeros: + image: evilfreelancer/docker-routeros:latest + restart: unless-stopped + cap_add: + - NET_ADMIN + devices: + - /dev/net/tun + - /dev/kvm + ports: + - "2222:22" + - "23:23" + - "80:80" + - "5900:5900" + - "8728:8728" + - "8729:8729" +``` + +### Creating a Custom `Dockerfile` + +You can easily create your own Dockerfile to include custom scripts or +configurations. The Docker image supports various tags, which are listed +[here](https://hub.docker.com/r/evilfreelancer/docker-routeros/tags/). +By default, the `latest` tag is used if no tag is specified. ```dockerfile FROM evilfreelancer/docker-routeros @@ -18,53 +66,11 @@ ADD ["your-scripts.sh", "/"] RUN /your-scripts.sh ``` -### Use image from docker hub +### Building from Source -```bash -docker pull evilfreelancer/docker-routeros -docker run -d -p 2222:22 -p 8728:8728 -p 8729:8729 -p 5900:5900 -ti evilfreelancer/docker-routeros -``` - -### Use in docker-compose.yml - -Example is [here](docker-compose.yml). - -```yml -version: "3" - -services: - - routeros-6-42: - image: evilfreelancer/docker-routeros:6.42.12 - restart: unless-stopped - cap_add: - - NET_ADMIN - devices: - - /dev/net/tun - ports: - - "12222:22" - - "12223:23" - - "18728:8728" - - "18729:8729" - - routeros-6-44: - image: evilfreelancer/docker-routeros:6.46.5 - restart: unless-stopped - cap_add: - - NET_ADMIN - devices: - - /dev/net/tun - ports: - - "22222:22" - - "22223:23" - - "28728:8728" - - "28729:8729" - -``` - -### Build from sources - -For this you need download project and build everything from scratch: +If you prefer to build the Docker image from source, the commands below +will guide you through cloning the repository, building the image, and +running a RouterOS container. ```bash git clone https://github.com/EvilFreelancer/docker-routeros.git @@ -73,20 +79,29 @@ docker build . --tag ros docker run -d -p 2222:22 -p 8728:8728 -p 8729:8729 -p 5900:5900 -ti ros ``` -Now you can connect to your RouterOS container via VNC protocol -(on localhost 5900 port) and via SSH (on localhost 2222 port). +After launching the container, you can access your RouterOS instance +via VNC (port 5900) and SSH (port 2222). -## List of exposed ports +## Exposed Ports -| Description | Ports | -|-------------|-------| +The table below summarizes the ports exposed by the Docker image, +catering to various services and protocols used by RouterOS. + +| Description | Ports | +|-------------|---------------------------------------| | Defaults | 21, 22, 23, 80, 443, 8291, 8728, 8729 | -| IPSec | 50, 51, 500/udp, 4500/udp | -| OpenVPN | 1194/tcp, 1194/udp | -| L2TP | 1701 | -| PPTP | 1723 | +| IPSec | 50, 51, 500/udp, 4500/udp | +| OpenVPN | 1194/tcp, 1194/udp | +| L2TP | 1701 | +| PPTP | 1723 | ## Links -* https://github.com/joshkunz/qemu-docker -* https://github.com/ennweb/docker-kvm +For more insights into Docker and virtualization technologies +related to RouterOS and networking, explore the following resources: + +* [Mikrotik RouterOS in Docker using Qemu](https://habr.com/ru/articles/498012/) - An article on Habr that provides a guide on setting up Mikrotik RouterOS in Docker using Qemu, ideal for developers and network engineers interested in RouterOS virtualization. +* [RouterOS API Client](https://github.com/EvilFreelancer/routeros-api-php) - GitHub repository for the RouterOS API PHP library, useful for interfacing with MikroTik devices. +* [VR Network Lab](https://github.com/vrnetlab/vrnetlab) - A project for running network equipment in Docker containers, recommended for production-level RouterOS simulations. +* [qemu-docker](https://github.com/joshkunz/qemu-docker) - A resource for integrating QEMU with Docker, enabling virtual machine emulation within containers. +* [QEMU/KVM on Docker](https://github.com/ennweb/docker-kvm) - Demonstrates using QEMU/KVM virtualization within Docker containers for improved performance.