From 0f338718506040fd2cba4e53726158f874d67c46 Mon Sep 17 00:00:00 2001 From: Christoph Haas Date: Sat, 29 Oct 2022 13:18:32 +0200 Subject: [PATCH] peer expiry feature: update api docs and readme --- Makefile | 2 +- README.md | 113 +++++++++++++++++---------------- internal/server/docs/docs.go | 119 +++++++++++++++-------------------- 3 files changed, 109 insertions(+), 125 deletions(-) diff --git a/Makefile b/Makefile index 06e371c..6c37492 100644 --- a/Makefile +++ b/Makefile @@ -52,7 +52,7 @@ docker-push: docker push $(IMAGE) api-docs: - cd internal/server; swag init --propertyStrategy pascalcase --parseDependency --parseInternal --generalInfo api.go + cd internal; swag init --propertyStrategy pascalcase --parseInternal --generalInfo server/api.go --output server/docs/ $(GOCMD) fmt internal/server/docs/docs.go $(BUILDDIR)/%-amd64: cmd/%/main.go dep phony diff --git a/README.md b/README.md index 269cc83..19efb90 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,7 @@ It also supports LDAP (Active Directory or OpenLDAP) as authentication provider. * Can be used with existing WireGuard setups * Support for multiple WireGuard interfaces * REST API for management and client deployment + * Peer Expiry Feature ![Screenshot](screenshot.png) @@ -108,61 +109,63 @@ For example: `CONFIG_FILE=/home/test/config.yml ./wg-portal-amd64`. ### Configuration Options The following configuration options are available: -| environment | yaml | yaml_parent | default_value | description | -|----------------------------|-------------------------|-------------|-------------------------------------------------|-------------------------------------------------------------------------------------------| -| LISTENING_ADDRESS | listeningAddress | core | :8123 | The address on which the web server is listening. Optional IP address and port, e.g.: 127.0.0.1:8080. | -| EXTERNAL_URL | externalUrl | core | http://localhost:8123 | The external URL where the web server is reachable. This link is used in emails that are created by the WireGuard Portal. | -| WEBSITE_TITLE | title | core | WireGuard VPN | The website title. | -| COMPANY_NAME | company | core | WireGuard Portal | The company name (for branding). | -| MAIL_FROM | mailFrom | core | WireGuard VPN | The email address from which emails are sent. | -| LOGO_URL | logoUrl | core | /img/header-logo.png | The logo displayed in the page's header. | -| ADMIN_USER | adminUser | core | admin@wgportal.local | The administrator user. Must be a valid email address. | -| ADMIN_PASS | adminPass | core | wgportal | The administrator password. If unchanged, a random password will be set on first startup. | -| EDITABLE_KEYS | editableKeys | core | true | Allow to edit key-pairs in the UI. | -| CREATE_DEFAULT_PEER | createDefaultPeer | core | false | If an LDAP user logs in for the first time, a new WireGuard peer will be created on the WG_DEFAULT_DEVICE if this option is enabled. | -| SELF_PROVISIONING | selfProvisioning | core | false | Allow registered users to automatically create peers via the RESTful API. | -| WG_EXPORTER_FRIENDLY_NAMES | wgExporterFriendlyNames | core | false | Enable integration with [prometheus_wireguard_exporter friendly name](https://github.com/MindFlavor/prometheus_wireguard_exporter#friendly-tags). | -| LDAP_ENABLED | ldapEnabled | core | false | Enable or disable the LDAP backend. | -| SESSION_SECRET | sessionSecret | core | secret | Use a custom secret to encrypt session data. | -| DATABASE_TYPE | typ | database | sqlite | Either mysql or sqlite. | -| DATABASE_HOST | host | database | | The mysql server address. | -| DATABASE_PORT | port | database | | The mysql server port. | -| DATABASE_NAME | database | database | data/wg_portal.db | For sqlite database: the database file-path, otherwise the database name. | -| DATABASE_USERNAME | user | database | | The mysql user. | -| DATABASE_PASSWORD | password | database | | The mysql password. | -| EMAIL_HOST | host | email | 127.0.0.1 | The email server address. | -| EMAIL_PORT | port | email | 25 | The email server port. | -| EMAIL_TLS | tls | email | false | Use STARTTLS. DEPRECATED: use EMAIL_ENCRYPTION instead. | -| EMAIL_ENCRYPTION | encryption | email | none | Either none, tls or starttls. | -| EMAIL_CERT_VALIDATION | certcheck | email | false | Validate the email server certificate. | -| EMAIL_USERNAME | user | email | | An optional username for SMTP authentication. | -| EMAIL_PASSWORD | pass | email | | An optional password for SMTP authentication. | -| EMAIL_AUTHTYPE | auth | email | plain | Either plain, login or crammd5. If username and password are empty, this value is ignored. | -| WG_DEVICES | devices | wg | wg0 | A comma separated list of WireGuard devices. | -| WG_DEFAULT_DEVICE | defaultDevice | wg | wg0 | This device is used for auto-created peers (if CREATE_DEFAULT_PEER is enabled). | -| WG_CONFIG_PATH | configDirectory | wg | /etc/wireguard | If set, interface configuration updates will be written to this path, filename: .conf. | -| MANAGE_IPS | manageIPAddresses | wg | true | Handle IP address setup of interface, only available on linux. | -| LDAP_URL | url | ldap | ldap://srv-ad01.company.local:389 | The LDAP server url. | -| LDAP_STARTTLS | startTLS | ldap | true | Use STARTTLS. | -| LDAP_CERT_VALIDATION | certcheck | ldap | false | Validate the LDAP server certificate. | -| LDAP_BASEDN | dn | ldap | DC=COMPANY,DC=LOCAL | The base DN for searching users. | -| LDAP_USER | user | ldap | company\\\\ldap_wireguard | The bind user. | -| LDAP_PASSWORD | pass | ldap | SuperSecret | The bind password. | -| LDAP_LOGIN_FILTER | loginFilter | ldap | (&(objectClass=organizationalPerson)(mail={{login_identifier}})(!userAccountControl:1.2.840.113556.1.4.803:=2)) | {{login_identifier}} will be replaced with the login email address. | -| LDAP_SYNC_FILTER | syncFilter | ldap | (&(objectClass=organizationalPerson)(!userAccountControl:1.2.840.113556.1.4.803:=2)(mail=*)) | The filter string for the LDAP synchronization service. | -| LDAP_ADMIN_GROUP | adminGroup | ldap | CN=WireGuardAdmins,OU=_O_IT,DC=COMPANY,DC=LOCAL | Users in this group are marked as administrators. | -| LDAP_ATTR_EMAIL | attrEmail | ldap | mail | User email attribute. | -| LDAP_ATTR_FIRSTNAME | attrFirstname | ldap | givenName | User firstname attribute. | -| LDAP_ATTR_LASTNAME | attrLastname | ldap | sn | User lastname attribute. | -| LDAP_ATTR_PHONE | attrPhone | ldap | telephoneNumber | User phone number attribute. | -| LDAP_ATTR_GROUPS | attrGroups | ldap | memberOf | User groups attribute. | -| LDAP_CERT_CONN | ldapCertConn | ldap | false | Allow connection with certificate against LDAP server without user/password | -| LDAPTLS_CERT | ldapTlsCert | ldap | | The LDAP cert's path | -| LDAPTLS_KEY | ldapTlsKey | ldap | | The LDAP key's path | -| LOG_LEVEL | | | debug | Specify log level, one of: trace, debug, info, off. | -| LOG_JSON | | | false | Format log output as JSON. | -| LOG_COLOR | | | true | Colorize log output. | -| CONFIG_FILE | | | config.yml | The config file path. | +| environment | yaml | yaml_parent | default_value | description | +|----------------------------|-------------------------|-------------|-----------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| LISTENING_ADDRESS | listeningAddress | core | :8123 | The address on which the web server is listening. Optional IP address and port, e.g.: 127.0.0.1:8080. | +| EXTERNAL_URL | externalUrl | core | http://localhost:8123 | The external URL where the web server is reachable. This link is used in emails that are created by the WireGuard Portal. | +| WEBSITE_TITLE | title | core | WireGuard VPN | The website title. | +| COMPANY_NAME | company | core | WireGuard Portal | The company name (for branding). | +| MAIL_FROM | mailFrom | core | WireGuard VPN | The email address from which emails are sent. | +| LOGO_URL | logoUrl | core | /img/header-logo.png | The logo displayed in the page's header. | +| ADMIN_USER | adminUser | core | admin@wgportal.local | The administrator user. Must be a valid email address. | +| ADMIN_PASS | adminPass | core | wgportal | The administrator password. If unchanged, a random password will be set on first startup. | +| EDITABLE_KEYS | editableKeys | core | true | Allow to edit key-pairs in the UI. | +| CREATE_DEFAULT_PEER | createDefaultPeer | core | false | If an LDAP user logs in for the first time, a new WireGuard peer will be created on the WG_DEFAULT_DEVICE if this option is enabled. | +| SELF_PROVISIONING | selfProvisioning | core | false | Allow registered users to automatically create peers via the RESTful API. | +| WG_EXPORTER_FRIENDLY_NAMES | wgExporterFriendlyNames | core | false | Enable integration with [prometheus_wireguard_exporter friendly name](https://github.com/MindFlavor/prometheus_wireguard_exporter#friendly-tags). | +| LDAP_ENABLED | ldapEnabled | core | false | Enable or disable the LDAP backend. | +| SESSION_SECRET | sessionSecret | core | secret | Use a custom secret to encrypt session data. | +| BACKGROUND_TASK_INTERVAL | backgroundTaskInterval | core | 900 | The interval (in seconds) for the background tasks (like peer expiry check). | +| DATABASE_TYPE | typ | database | sqlite | Either mysql or sqlite. | +| DATABASE_HOST | host | database | | The mysql server address. | +| DATABASE_PORT | port | database | | The mysql server port. | +| DATABASE_NAME | database | database | data/wg_portal.db | For sqlite database: the database file-path, otherwise the database name. | +| DATABASE_USERNAME | user | database | | The mysql user. | +| DATABASE_PASSWORD | password | database | | The mysql password. | +| EMAIL_HOST | host | email | 127.0.0.1 | The email server address. | +| EMAIL_PORT | port | email | 25 | The email server port. | +| EMAIL_TLS | tls | email | false | Use STARTTLS. DEPRECATED: use EMAIL_ENCRYPTION instead. | +| EMAIL_ENCRYPTION | encryption | email | none | Either none, tls or starttls. | +| EMAIL_CERT_VALIDATION | certcheck | email | false | Validate the email server certificate. | +| EMAIL_USERNAME | user | email | | An optional username for SMTP authentication. | +| EMAIL_PASSWORD | pass | email | | An optional password for SMTP authentication. | +| EMAIL_AUTHTYPE | auth | email | plain | Either plain, login or crammd5. If username and password are empty, this value is ignored. | +| WG_DEVICES | devices | wg | wg0 | A comma separated list of WireGuard devices. | +| WG_DEFAULT_DEVICE | defaultDevice | wg | wg0 | This device is used for auto-created peers (if CREATE_DEFAULT_PEER is enabled). | +| WG_CONFIG_PATH | configDirectory | wg | /etc/wireguard | If set, interface configuration updates will be written to this path, filename: .conf. | +| MANAGE_IPS | manageIPAddresses | wg | true | Handle IP address setup of interface, only available on linux. | +| USER_MANAGE_PEERS | userManagePeers | wg | false | Logged in user can create or update peers (partially). | +| LDAP_URL | url | ldap | ldap://srv-ad01.company.local:389 | The LDAP server url. | +| LDAP_STARTTLS | startTLS | ldap | true | Use STARTTLS. | +| LDAP_CERT_VALIDATION | certcheck | ldap | false | Validate the LDAP server certificate. | +| LDAP_BASEDN | dn | ldap | DC=COMPANY,DC=LOCAL | The base DN for searching users. | +| LDAP_USER | user | ldap | company\\\\ldap_wireguard | The bind user. | +| LDAP_PASSWORD | pass | ldap | SuperSecret | The bind password. | +| LDAP_LOGIN_FILTER | loginFilter | ldap | (&(objectClass=organizationalPerson)(mail={{login_identifier}})(!userAccountControl:1.2.840.113556.1.4.803:=2)) | {{login_identifier}} will be replaced with the login email address. | +| LDAP_SYNC_FILTER | syncFilter | ldap | (&(objectClass=organizationalPerson)(!userAccountControl:1.2.840.113556.1.4.803:=2)(mail=*)) | The filter string for the LDAP synchronization service. | +| LDAP_ADMIN_GROUP | adminGroup | ldap | CN=WireGuardAdmins,OU=_O_IT,DC=COMPANY,DC=LOCAL | Users in this group are marked as administrators. | +| LDAP_ATTR_EMAIL | attrEmail | ldap | mail | User email attribute. | +| LDAP_ATTR_FIRSTNAME | attrFirstname | ldap | givenName | User firstname attribute. | +| LDAP_ATTR_LASTNAME | attrLastname | ldap | sn | User lastname attribute. | +| LDAP_ATTR_PHONE | attrPhone | ldap | telephoneNumber | User phone number attribute. | +| LDAP_ATTR_GROUPS | attrGroups | ldap | memberOf | User groups attribute. | +| LDAP_CERT_CONN | ldapCertConn | ldap | false | Allow connection with certificate against LDAP server without user/password | +| LDAPTLS_CERT | ldapTlsCert | ldap | | The LDAP cert's path | +| LDAPTLS_KEY | ldapTlsKey | ldap | | The LDAP key's path | +| LOG_LEVEL | | | debug | Specify log level, one of: trace, debug, info, off. | +| LOG_JSON | | | false | Format log output as JSON. | +| LOG_COLOR | | | true | Colorize log output. | +| CONFIG_FILE | | | config.yml | The config file path. | ### Sample yaml configuration config.yml: diff --git a/internal/server/docs/docs.go b/internal/server/docs/docs.go index 6b4b029..7fd5fd8 100644 --- a/internal/server/docs/docs.go +++ b/internal/server/docs/docs.go @@ -1,17 +1,10 @@ -// Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT +// Package docs GENERATED BY SWAG; DO NOT EDIT // This file was generated by swaggo/swag package docs -import ( - "bytes" - "encoding/json" - "strings" - "text/template" +import "github.com/swaggo/swag" - "github.com/swaggo/swag" -) - -var doc = `{ +const docTemplate = `{ "schemes": {{ marshal .Schemes }}, "swagger": "2.0", "info": { @@ -1267,10 +1260,13 @@ var doc = `{ "type": "string" }, "Mtu": { - "type": "integer" + "type": "integer", + "maximum": 1500, + "minimum": 0 }, "PersistentKeepalive": { - "type": "integer" + "type": "integer", + "minimum": 0 } } }, @@ -1344,16 +1340,19 @@ var doc = `{ "type": "string" }, "DefaultPersistentKeepalive": { - "type": "integer" + "type": "integer", + "minimum": 0 }, "DeviceName": { "type": "string" }, "DisplayName": { - "type": "string" + "type": "string", + "maxLength": 200 }, "FirewallMark": { - "type": "integer" + "type": "integer", + "minimum": 0 }, "IPsStr": { "description": "comma separated list of the IPs of the client, wg-quick addition", @@ -1364,7 +1363,9 @@ var doc = `{ }, "Mtu": { "description": "the interface MTU, wg-quick addition", - "type": "integer" + "type": "integer", + "maximum": 1500, + "minimum": 0 }, "PostDown": { "description": "post down script, wg-quick addition", @@ -1399,7 +1400,11 @@ var doc = `{ "type": "boolean" }, "Type": { - "type": "string" + "type": "string", + "enum": [ + "client", + "server" + ] }, "UpdatedAt": { "type": "string" @@ -1438,11 +1443,18 @@ var doc = `{ "DeactivatedAt": { "type": "string" }, + "DeactivatedReason": { + "type": "string" + }, "DeviceName": { "type": "string" }, "DeviceType": { - "type": "string" + "type": "string", + "enum": [ + "client", + "server" + ] }, "Email": { "type": "string" @@ -1450,23 +1462,30 @@ var doc = `{ "Endpoint": { "type": "string" }, + "ExpiresAt": { + "type": "string" + }, "IPsStr": { "description": "a comma separated list of IPs of the client", "type": "string" }, "Identifier": { "description": "Identifier AND Email make a WireGuard peer unique", - "type": "string" + "type": "string", + "maxLength": 64 }, "IgnoreGlobalSettings": { "type": "boolean" }, "Mtu": { "description": "Global Device Settings (can be ignored, only make sense if device is in server mode)", - "type": "integer" + "type": "integer", + "maximum": 1500, + "minimum": 0 }, "PersistentKeepalive": { - "type": "integer" + "type": "integer", + "minimum": 0 }, "PresharedKey": { "type": "string" @@ -1502,56 +1521,18 @@ var doc = `{ } }` -type swaggerInfo struct { - Version string - Host string - BasePath string - Schemes []string - Title string - Description string -} - // SwaggerInfo holds exported Swagger Info so clients can modify it -var SwaggerInfo = swaggerInfo{ - Version: "1.0", - Host: "", - BasePath: "/api/v1", - Schemes: []string{}, - Title: "WireGuard Portal API", - Description: "WireGuard Portal API for managing users and peers.", -} - -type s struct{} - -func (s *s) ReadDoc() string { - sInfo := SwaggerInfo - sInfo.Description = strings.Replace(sInfo.Description, "\n", "\\n", -1) - - t, err := template.New("swagger_info").Funcs(template.FuncMap{ - "marshal": func(v interface{}) string { - a, _ := json.Marshal(v) - return string(a) - }, - "escape": func(v interface{}) string { - // escape tabs - str := strings.Replace(v.(string), "\t", "\\t", -1) - // replace " with \", and if that results in \\", replace that with \\\" - str = strings.Replace(str, "\"", "\\\"", -1) - return strings.Replace(str, "\\\\\"", "\\\\\\\"", -1) - }, - }).Parse(doc) - if err != nil { - return doc - } - - var tpl bytes.Buffer - if err := t.Execute(&tpl, sInfo); err != nil { - return doc - } - - return tpl.String() +var SwaggerInfo = &swag.Spec{ + Version: "1.0", + Host: "", + BasePath: "/api/v1", + Schemes: []string{}, + Title: "WireGuard Portal API", + Description: "WireGuard Portal API for managing users and peers.", + InfoInstanceName: "swagger", + SwaggerTemplate: docTemplate, } func init() { - swag.Register(swag.Name, &s{}) + swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo) }