xterm-inator / mikroguard

Web interface for managing WireGuard peers on MikroTik routers

MikroGuard

**Recently renamed from microguard. For now the microguard ghcr image will continue to be updated inline with the new mikroguard ghcr for backwards compatibility, But would recommend switching to the new image. No migration steps are needed, the only difference is the name and the new mikroguard image won't have versions before v1.1.4

MikroGuard is a robust web-based management tool designed to streamline the handling of WireGuard VPN clients on MikroTik routers. It simplifies user addition, access revocation, and provides a real-time view of connection statistics.

Login	Users	Connection

Table of Contents

• Features
• Requirements
• Setup
  • Adding a User to MikroTik for MikroGuard
  • Creating a Road Warrior Wireguard Interface for MikroGuard
  • Server Installation
• Local Development and Testing with Docker Compose
• Troubleshooting
• Contributing
• License

Features

• Client Management: Streamline the creation and management of WireGuard clients on MikroTik routers.
• Real-time Monitoring: Access real-time connection statistics and usage insights.
• Access Control: Easily grant or revoke access for individual clients.
• Google SSO: Secure sign-in using Google's Single Sign-On system.

Requirements

• MikroTik router with RouterOS version 7.0 or newer.
• Docker for running the MikroGuard server.

Self Sanity Check

If you would like to check what this program will run on your router before allowing access, check files 'api/app/RouterOS/WireGuard.php' and 'api/app/RouterOS/IPAddress.php'.

These files contain all access to the router so you can see the commands run.

Also, no user input is ever passed to the router; only values you, as the admin, have entered through environment variables.

Setup

Adding a User to MikroTik for MikroGuard

Using Winbox:

1. Log in to your MikroTik router using Winbox.
2. Navigate to the "System" menu and select "Users".
3. Click on the "Groups" tab.
4. Click on the "Add New" button to create a new user group.
5. Enter a name for the group, such as "MikroGuard-group" and click on the "OK" button.
6. In the "Permissions" tab, select the desired permissions for the group. For MikroGuard, the user group should have read, write, and API access.
7. Click on the "Apply" button to save the changes.
8. Click on the "Users" tab.
9. Enter the user's details, such as their name and password.

Warning: Always input the correct local subnet into the allowed address. If unsure about the configuration, seek expert advice.

11. In the "Groups" tab, select the "MikroGuard-group" group you just created.
12. Click on the "Apply" button to save the changes.

Using Command Line:

To set up a new user group and user, input:

This will create a new user group named "MikroGuard-group" with the necessary permissions for MikroGuard.

/user group add name=MikroGuard-group policy=local,read,write,test,api,winbox,password

Enter the following command to create a new user:

Replace "username" with the desired username and "userpassword" with the desired password for the new user.

/user add name=username group=MikroGuard-group password=userpassword

Warning: Ensure correct subnet configuration as highlighted in the Winbox method.

Creating a Road Warrior WireGuard Interface for MikroGuard

1. Access your MikroTik router via Winbox.
2. Go to "WireGuard" > "Add".
3. Label the interface (e.g., "wireguard road warrior") and click Apply.
4. Document the public key of the freshly created WireGuard server for subsequent use.

Server Installation

1. Ensure Docker is up and running on your server.
2. Generate an app key via this generator for use in upcoming commands.
3. Deploy MikroGuard using:

If you don't want to use google sso remove the google environment variables from the following commands

Docker Command

docker run -d
--name MikroGuard
-p 8000:8000
-v /path/to/data:/opt/app/storage
-e APP_KEY=
-e GOOGLE_CLIENT_ID=
-e GOOGLE_CLIENT_SECRET=
-e GOOGLE_REDIRECT_URL='https://my.public.address/api/auth/oauth/google/callback'
-e ROUTEROS_HOST='192.168.0.1'
-e ROUTEROS_PORT='8728'
-e ROUTEROS_USER='wireguard'
-e ROUTEROS_PASS='wireguard pass'
-e ROUTEROS_WIREGUARD_INTERFACE='wireguard' #wireguard interface name 
-e ROUTEROS_WIREGUARD_ENDPOINT='192.168.0.1:13231' #ip:port for wireguard interface
-e APP_URL='https://my.public.address'
ghcr.io/xterm-inator/mikroguard:latest

Docker Compose:

version: '3.8'
services:
  MikroGuard:
    image: ghcr.io/xterm-inator/mikroguard:latest
    container_name: MikroGuard
    restart: always
    ports:
      - 8000:8000
    volumes:
      - /path/to/data:/opt/app/storage
    environment:
      - APP_KEY=
      - GOOGLE_CLIENT_ID=
      - GOOGLE_CLIENT_SECRET=
      - GOOGLE_REDIRECT_URL=https://my.public.address/api/auth/oauth/google/callback
      - ROUTEROS_HOST=192.168.0.1
      - ROUTEROS_PORT=8728
      - ROUTEROS_USER=wireguard
      - ROUTEROS_PASS=wireguard pass
      - ROUTEROS_WIREGUARD_INTERFACE=wireguard
      - ROUTEROS_WIREGUARD_ENDPOINT=192.168.0.1:13231
      - APP_URL=https://my.public.address

Environment Varibles: This is a list of the most useful environment variables. To find all available look in api/config files

Variable	Description	Default
APP_KEY*	App key used mainly for encryption, set using this generator
APP_URL*	The url this instance will be accessed from, can be localhost, an IP address or a domain eg. http://localhost:8000	http://localhost:8000
GOOGLE_CLIENT_ID	Google OAuth Client ID (Only required if using google auth)
GOOGLE_CLIENT_SECRET	Google OAuth Client Secret (Only required if using google auth)
GOOGLE_REDIRECT_URL	Google OAuth Redirect Url, eg. https://my.public.address/api/auth/oauth/google/callback (Only required if using google auth)
ROUTEROS_HOST*	IP address of your MikroTik router
ROUTEROS_PORT*	API port to access the router
ROUTEROS_USER*	User to log into the router
ROUTEROS_PASS*	Password to use to log into the router
ROUTEROS_WIREGUARD_INTERFACE*	WireGuard interface name, must match the wireguard interface name created on the MikroTik router eg. wireguard Road Warrior
ROUTEROS_WIREGUARD_ENDPOINT*	Your public IP clients use to connect to your WireGurad server on your MikroTik Router including the port eg. 123.123.123.123:12345
ROUTEROS_WIREGUARD_SERVER_NAME	Default server name given to clients, can be anything	WireGuard Server
ROUTEROS_WIREGUARD_DNS	Client DNS server to use	1.1.1.1
ROUTEROS_WIREGUARD_ALLOWED_IPS	Client IPs to forward, Defaults to everything	0.0.0.0/0

*Required

Initial User

To create the initial user run: (replace: [email protected] with your email)

docker compose exec MikroGuard php artisan app:create-user [email protected] admin 

Local Development and Testing with Docker Compose

To facilitate local development and testing, we've incorporated Docker Compose. This allows developers to run the entire MikroGuard stack locally without complex setups.

Prerequisites:

• Docker
• Docker Compose
• Git

Steps:

1. Clone the Repository: Use Git to clone the MikroGuard repository to your local machine:

   git clone [email protected]:xterm-inator/MikroGuard.git
   # Navigate into the repository directory:
   cd MikroGuard

2. Set Up Environment Variables: Before starting the services using Docker Compose, you may need to configure some environment variables. Copy the sample environment file and adjust the settings as necessary:

   cp api/.env.example api/.env

   Edit the .env file with appropriate values. Make sure to generate and set values for necessary keys.

3. Build Containers:

   docker compose build --parallel

4. Install Dependencies: Using docker run there are some dependencies that need to be setup:

   docker compose run api composer install
   docker compose run api npm i
   docker compose run api php artisan key:generate
   docker compose run api php artisan migrate
   docker compose run vue npm i

5. Create an Initial User:

   docker compose run api php artisan app:create-user [email protected] admin

6. Run with Docker Compose: Start the MikroGuard stack using Docker Compose:

   docker compose up

   This will build and start all necessary containers. Once done, the MikroGuard interface should be accessible at http://localhost:3000.

7. Shutdown and Cleanup: When you're done with local development/testing, you can stop the Docker Compose services:

   docker compose down

Troubleshooting

Error: Session store not set on request

This error is normally caused when the browser is accessing the server from an address that is different to the APP_URL set in the environment variables.

Try setting this to the address you are using, can be localhost, an IP address or a domain eg. http://localhost:8000

Contributing

Contribute to MikroGuard by submitting a pull request or issue on GitHub. We welcome bug reports, feature suggestions, and code enhancements from the community.

License

MikroGuard is licensed under the GNU General Public License v3.0. Details are in the LICENSE.md file.

mikroguard's Issues

can't login

Hi
start compose

version: '3.8'
services:
microguard:
image: ghcr.io/xterm-inator/microguard:latest
container_name: microguard
restart: always
ports:
- 80:80
volumes:
- /path/to/data:/opt/app/storage
environment:
- APP_KEY=mykey
- GOOGLE_CLIENT_ID=
- GOOGLE_CLIENT_SECRET=
- GOOGLE_REDIRECT_URL=https://my.public.address/api/auth/oauth/google/callback
- ROUTEROS_HOST=192.168.0.1
- ROUTEROS_PORT=8728
- ROUTEROS_USER=wireguard
- ROUTEROS_PASS=wireguard pass
- ROUTEROS_WIREGUARD_INTERFACE=wireguard
- ROUTEROS_WIREGUARD_ENDPOINT=192.168.0.1:13231
- APP_URL=https://my.public.address

create user
docker compose exec microguard php artisan app:create-user [email protected] admin
can't login
docker logs microguard

500 POST /api/auth ..................................... 25.15 mb 80.23 ms [2024-04-24 08:50:03] local.ERROR: Session store not set on request. {"userId":2,"exception":"[object] (RuntimeException(code: 0): Session store not set on request. at /opt/app/vendor/laravel/framework/src/Illuminate/Http/Request.php:564)

New feature: Custom routes & DNS

Can you add an enviroment for pushing certain routes and DNS address?

Setting up Mikroguard and mikrotik device with existing peers.

Hello dear - thank you for this great software. When i try to add new user - it ignores all existing peers and tries to create new peer with dublicate IP. It would be great if it automatically add all existing peers. And second thing - is it possbile to use as a peer name not just email, but any name? Thank you.

Create remote image and add new features

Hi David
Is it possible to add traffic consumption and expiration date for the user? This should be done by the front itself and disable the peer when it reaches the desired traffic, for example 50 gigs, or check the date by the system and when it reaches the desired date, disable it by api and allow the number of connections to be added to the peer. For example, when we confirm a user to connect in the user creation, how many users can't use the same config and also prepare it as a container for Mikrotik? I am new to Docker and your explanation is a bit complicated for me

Error: Session store not set on request

Still struggling with the problem, according to your notes, I checked APP_URL, without success. I also played around with ports and also without success. There are thoughts in what can be.

could I host it internally without google sso

amazing looking app just dont want to be using google sign on :) was looking for my homelab

login

Hi David
What is the username and password of the login page?
thanks a lot

Azure SSO integration

Wondering if Azure Integration is on the roadmap. Can some documentation be added related to SSO like what exists for Google SSO and what is required to get Azure SSO to work in MikroGuard.