diff options
Diffstat (limited to 'src/go/collectors/go.d.plugin/modules/openvpn')
18 files changed, 1384 insertions, 0 deletions
diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/README.md b/src/go/collectors/go.d.plugin/modules/openvpn/README.md new file mode 120000 index 000000000..020da3ac6 --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/README.md @@ -0,0 +1 @@ +integrations/openvpn.md
\ No newline at end of file diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/charts.go b/src/go/collectors/go.d.plugin/modules/openvpn/charts.go new file mode 100644 index 000000000..435c2151a --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/charts.go @@ -0,0 +1,62 @@ +// SPDX-License-Identifier: GPL-3.0-or-later + +package openvpn + +import "github.com/netdata/netdata/go/go.d.plugin/agent/module" + +type ( + // Charts is an alias for module.Charts + Charts = module.Charts + // Dims is an alias for module.Dims + Dims = module.Dims +) + +var charts = Charts{ + { + ID: "active_clients", + Title: "Total Number Of Active Clients", + Units: "clients", + Fam: "clients", + Ctx: "openvpn.active_clients", + Dims: Dims{ + {ID: "clients"}, + }, + }, + { + ID: "total_traffic", + Title: "Total Traffic", + Units: "kilobits/s", + Fam: "traffic", + Ctx: "openvpn.total_traffic", + Type: module.Area, + Dims: Dims{ + {ID: "bytes_in", Name: "in", Algo: module.Incremental, Mul: 8, Div: 1000}, + {ID: "bytes_out", Name: "out", Algo: module.Incremental, Mul: 8, Div: -1000}, + }, + }, +} + +var userCharts = Charts{ + { + ID: "%s_user_traffic", + Title: "User Traffic", + Units: "kilobits/s", + Fam: "user %s", + Ctx: "openvpn.user_traffic", + Type: module.Area, + Dims: Dims{ + {ID: "%s_bytes_received", Name: "received", Algo: module.Incremental, Mul: 8, Div: 1000}, + {ID: "%s_bytes_sent", Name: "sent", Algo: module.Incremental, Mul: 8, Div: -1000}, + }, + }, + { + ID: "%s_user_connection_time", + Title: "User Connection Time", + Units: "seconds", + Fam: "user %s", + Ctx: "openvpn.user_connection_time", + Dims: Dims{ + {ID: "%s_connection_time", Name: "time"}, + }, + }, +} diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/client/client.go b/src/go/collectors/go.d.plugin/modules/openvpn/client/client.go new file mode 100644 index 000000000..ddbfdeafb --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/client/client.go @@ -0,0 +1,153 @@ +// SPDX-License-Identifier: GPL-3.0-or-later + +package client + +import ( + "fmt" + "regexp" + "strconv" + "strings" + + "github.com/netdata/netdata/go/go.d.plugin/pkg/socket" +) + +var ( + reLoadStats = regexp.MustCompile(`^SUCCESS: nclients=([0-9]+),bytesin=([0-9]+),bytesout=([0-9]+)`) + reVersion = regexp.MustCompile(`^OpenVPN Version: OpenVPN ([0-9]+)\.([0-9]+)\.([0-9]+) .+Management Version: ([0-9])`) +) + +const maxLinesToRead = 500 + +// New creates new OpenVPN client. +func New(config socket.Config) *Client { + return &Client{Client: socket.New(config)} +} + +// Client represents OpenVPN client. +type Client struct { + socket.Client +} + +// Users Users. +func (c *Client) Users() (Users, error) { + lines, err := c.get(commandStatus3, readUntilEND) + if err != nil { + return nil, err + } + return decodeUsers(lines) +} + +// LoadStats LoadStats. +func (c *Client) LoadStats() (*LoadStats, error) { + lines, err := c.get(commandLoadStats, readOneLine) + if err != nil { + return nil, err + } + return decodeLoadStats(lines) +} + +// Version Version. +func (c *Client) Version() (*Version, error) { + lines, err := c.get(commandVersion, readUntilEND) + if err != nil { + return nil, err + } + return decodeVersion(lines) +} + +func (c *Client) get(command string, stopRead stopReadFunc) (output []string, err error) { + var num int + var maxLinesErr error + err = c.Command(command, func(bytes []byte) bool { + line := string(bytes) + num++ + if num > maxLinesToRead { + maxLinesErr = fmt.Errorf("read line limit exceeded (%d)", maxLinesToRead) + return false + } + + // skip real-time messages + if strings.HasPrefix(line, ">") { + return true + } + + line = strings.Trim(line, "\r\n ") + output = append(output, line) + if stopRead != nil && stopRead(line) { + return false + } + return true + }) + if maxLinesErr != nil { + return nil, maxLinesErr + } + return output, err +} + +type stopReadFunc func(string) bool + +func readOneLine(_ string) bool { return true } + +func readUntilEND(s string) bool { return strings.HasSuffix(s, "END") } + +func decodeLoadStats(src []string) (*LoadStats, error) { + m := reLoadStats.FindStringSubmatch(strings.Join(src, " ")) + if len(m) == 0 { + return nil, fmt.Errorf("parse failed : %v", src) + } + return &LoadStats{ + NumOfClients: mustParseInt(m[1]), + BytesIn: mustParseInt(m[2]), + BytesOut: mustParseInt(m[3]), + }, nil +} + +func decodeVersion(src []string) (*Version, error) { + m := reVersion.FindStringSubmatch(strings.Join(src, " ")) + if len(m) == 0 { + return nil, fmt.Errorf("parse failed : %v", src) + } + return &Version{ + Major: mustParseInt(m[1]), + Minor: mustParseInt(m[2]), + Patch: mustParseInt(m[3]), + Management: mustParseInt(m[4]), + }, nil +} + +// works only for `status 3\n` +func decodeUsers(src []string) (Users, error) { + var users Users + + // [CLIENT_LIST common_name 178.66.34.194:54200 10.9.0.5 9319 8978 Thu May 9 05:01:44 2019 1557345704 username] + for _, v := range src { + if !strings.HasPrefix(v, "CLIENT_LIST") { + continue + } + parts := strings.Fields(v) + // Right after the connection there are no virtual ip, and both common name and username UNDEF + // CLIENT_LIST UNDEF 178.70.95.93:39324 1411 3474 Fri May 10 07:41:54 2019 1557441714 UNDEF + if len(parts) != 13 { + continue + } + u := User{ + CommonName: parts[1], + RealAddress: parts[2], + VirtualAddress: parts[3], + BytesReceived: mustParseInt(parts[4]), + BytesSent: mustParseInt(parts[5]), + ConnectedSince: mustParseInt(parts[11]), + Username: parts[12], + } + users = append(users, u) + } + return users, nil +} + +func mustParseInt(str string) int64 { + v, err := strconv.ParseInt(str, 10, 64) + if err != nil { + panic(err) + } + return v +} diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/client/client_test.go b/src/go/collectors/go.d.plugin/modules/openvpn/client/client_test.go new file mode 100644 index 000000000..c10673ed5 --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/client/client_test.go @@ -0,0 +1,98 @@ +// SPDX-License-Identifier: GPL-3.0-or-later + +package client + +import ( + "bufio" + "bytes" + "fmt" + "os" + "strings" + "testing" + + "github.com/netdata/netdata/go/go.d.plugin/pkg/socket" + "github.com/stretchr/testify/assert" +) + +var ( + testLoadStatsData, _ = os.ReadFile("testdata/load-stats.txt") + testVersionData, _ = os.ReadFile("testdata/version.txt") + testStatus3Data, _ = os.ReadFile("testdata/status3.txt") + testMaxLinesExceededData = strings.Repeat(">CLIENT:ESTABLISHED,0\n", 501) +) + +func TestNew(t *testing.T) { assert.IsType(t, (*Client)(nil), New(socket.Config{})) } + +func TestClient_GetVersion(t *testing.T) { + client := Client{Client: &mockSocketClient{}} + ver, err := client.Version() + assert.NoError(t, err) + expected := &Version{Major: 2, Minor: 3, Patch: 4, Management: 1} + assert.Equal(t, expected, ver) +} + +func TestClient_GetLoadStats(t *testing.T) { + client := Client{Client: &mockSocketClient{}} + stats, err := client.LoadStats() + assert.NoError(t, err) + expected := &LoadStats{NumOfClients: 1, BytesIn: 7811, BytesOut: 7667} + assert.Equal(t, expected, stats) +} + +func TestClient_GetUsers(t *testing.T) { + client := Client{ + Client: &mockSocketClient{}, + } + users, err := client.Users() + assert.NoError(t, err) + expected := Users{{ + CommonName: "pepehome", + RealAddress: "1.2.3.4:44347", + VirtualAddress: "10.9.0.5", + BytesReceived: 6043, + BytesSent: 5661, + ConnectedSince: 1555439465, + Username: "pepe", + }} + assert.Equal(t, expected, users) +} + +func TestClient_MaxLineExceeded(t *testing.T) { + client := Client{ + Client: &mockSocketClient{maxLineExceeded: true}, + } + _, err := client.Users() + assert.Error(t, err) +} + +type mockSocketClient struct { + maxLineExceeded bool +} + +func (m *mockSocketClient) Connect() error { return nil } + +func (m *mockSocketClient) Disconnect() error { return nil } + +func (m *mockSocketClient) Command(command string, process socket.Processor) error { + var s *bufio.Scanner + switch command { + default: + return fmt.Errorf("unknown command : %s", command) + case commandExit: + case commandVersion: + s = bufio.NewScanner(bytes.NewReader(testVersionData)) + case commandStatus3: + if m.maxLineExceeded { + s = bufio.NewScanner(strings.NewReader(testMaxLinesExceededData)) + break + } + s = bufio.NewScanner(bytes.NewReader(testStatus3Data)) + case commandLoadStats: + s = bufio.NewScanner(bytes.NewReader(testLoadStatsData)) + } + + for s.Scan() { + process(s.Bytes()) + } + return nil +} diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/client/commands.go b/src/go/collectors/go.d.plugin/modules/openvpn/client/commands.go new file mode 100644 index 000000000..f06b05c90 --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/client/commands.go @@ -0,0 +1,38 @@ +// SPDX-License-Identifier: GPL-3.0-or-later + +package client + +/* +https://openvpn.net/community-resources/management-interface/ + +OUTPUT FORMAT +------------- + +(1) Command success/failure indicated by "SUCCESS: [text]" or + "ERROR: [text]". + +(2) For commands which print multiple lines of output, + the last line will be "END". + +(3) Real-time messages will be in the form ">[source]:[text]", + where source is "CLIENT", "ECHO", "FATAL", "HOLD", "INFO", "LOG", + "NEED-OK", "PASSWORD", or "STATE". +*/ + +var ( + // Close the management session, and resume listening on the + // management port for connections from other clients. Currently, + // the OpenVPN daemon can at most support a single management client + // any one time. + commandExit = "exit\n" + + // Show current daemon status information, in the same format as + // that produced by the OpenVPN --status directive. + commandStatus3 = "status 3\n" + + // no description in docs ¯\(°_o)/¯ + commandLoadStats = "load-stats\n" + + // Show the current OpenVPN and Management Interface versions. + commandVersion = "version\n" +) diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/client/testdata/load-stats.txt b/src/go/collectors/go.d.plugin/modules/openvpn/client/testdata/load-stats.txt new file mode 100644 index 000000000..39c19ac5b --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/client/testdata/load-stats.txt @@ -0,0 +1 @@ +SUCCESS: nclients=1,bytesin=7811,bytesout=7667 diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/client/testdata/status3.txt b/src/go/collectors/go.d.plugin/modules/openvpn/client/testdata/status3.txt new file mode 100644 index 000000000..1986703d2 --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/client/testdata/status3.txt @@ -0,0 +1,77 @@ +>CLIENT:ESTABLISHED,0 +>CLIENT:ENV,n_clients=1 +>CLIENT:ENV,ifconfig_pool_local_ip=10.9.0.6 +>CLIENT:ENV,ifconfig_pool_remote_ip=10.9.0.5 +>CLIENT:ENV,time_unix=1555439465 +>CLIENT:ENV,time_ascii=Wed Apr 17 03:31:05 2019 +>CLIENT:ENV,trusted_port=44347 +>CLIENT:ENV,trusted_ip=1.2.3.4 +>CLIENT:ENV,common_name=pepehome +>CLIENT:ENV,auth_control_file=/tmp/openvpn_acf_ae7f48d495d3d4cfb3065763b916d9ab.tmp +>CLIENT:ENV,untrusted_port=44347 +>CLIENT:ENV,untrusted_ip=1.2.3.4 +>CLIENT:ENV,username=pepe +>CLIENT:ENV,tls_serial_hex_0=04 +>CLIENT:ENV,tls_serial_0=4 +>CLIENT:ENV,tls_digest_0=be:83:8c:95:21:bf:f3:87:1a:35:86:d9:2e:f3:f5:d7:08:a9:db:7e +>CLIENT:ENV,tls_id_0=C=RU, ST=AM, L=Blagoveshchensk, O=L2ISBAD, OU=MyOrganizationalUnit, CN=pepehome, name=EasyRSA, emailAddress=me@myhost.mydomain +>CLIENT:ENV,X509_0_emailAddress=me@myhost.mydomain +>CLIENT:ENV,X509_0_name=EasyRSA +>CLIENT:ENV,X509_0_CN=pepehome +>CLIENT:ENV,X509_0_OU=MyOrganizationalUnit +>CLIENT:ENV,X509_0_O=L2ISBAD +>CLIENT:ENV,X509_0_L=Blagoveshchensk +>CLIENT:ENV,X509_0_ST=AM +>CLIENT:ENV,X509_0_C=RU +>CLIENT:ENV,tls_serial_hex_1=ad:4c:1e:65:e8:3c:ec:6f +>CLIENT:ENV,tls_serial_1=12487389289828379759 +>CLIENT:ENV,tls_digest_1=52:e2:1d:41:3f:34:09:70:4c:2d:71:8c:a7:28:fa:6b:66:2b:28:6e +>CLIENT:ENV,tls_id_1=C=RU, ST=AM, L=Blagoveshchensk, O=L2ISBAD, OU=MyOrganizationalUnit, CN=L2ISBAD CA, name=EasyRSA, emailAddress=me@myhost.mydomain +>CLIENT:ENV,X509_1_emailAddress=me@myhost.mydomain +>CLIENT:ENV,X509_1_name=EasyRSA +>CLIENT:ENV,X509_1_CN=L2ISBAD CA +>CLIENT:ENV,X509_1_OU=MyOrganizationalUnit +>CLIENT:ENV,X509_1_O=L2ISBAD +>CLIENT:ENV,X509_1_L=Blagoveshchensk +>CLIENT:ENV,X509_1_ST=AM +>CLIENT:ENV,X509_1_C=RU +>CLIENT:ENV,remote_port_1=1194 +>CLIENT:ENV,local_port_1=1194 +>CLIENT:ENV,proto_1=udp +>CLIENT:ENV,daemon_pid=4237 +>CLIENT:ENV,daemon_start_time=1555439449 +>CLIENT:ENV,daemon_log_redirect=0 +>CLIENT:ENV,daemon=1 +>CLIENT:ENV,verb=3 +>CLIENT:ENV,config=/etc/openvpn/server.conf +>CLIENT:ENV,ifconfig_local=10.8.0.1 +>CLIENT:ENV,ifconfig_remote=10.8.0.2 +>CLIENT:ENV,route_net_gateway=188.168.142.252 +>CLIENT:ENV,route_vpn_gateway=10.8.0.2 +>CLIENT:ENV,route_network_1=10.9.0.1 +>CLIENT:ENV,route_netmask_1=255.255.255.255 +>CLIENT:ENV,route_gateway_1=10.8.0.2 +>CLIENT:ENV,route_network_2=10.9.0.5 +>CLIENT:ENV,route_netmask_2=255.255.255.255 +>CLIENT:ENV,route_gateway_2=10.8.0.2 +>CLIENT:ENV,route_network_3=10.9.0.9 +>CLIENT:ENV,route_netmask_3=255.255.255.255 +>CLIENT:ENV,route_gateway_3=10.8.0.2 +>CLIENT:ENV,route_network_4=10.8.0.0 +>CLIENT:ENV,route_netmask_4=255.255.255.0 +>CLIENT:ENV,route_gateway_4=10.8.0.2 +>CLIENT:ENV,script_context=init +>CLIENT:ENV,tun_mtu=1500 +>CLIENT:ENV,link_mtu=1558 +>CLIENT:ENV,dev=tun99 +>CLIENT:ENV,dev_type=tun +>CLIENT:ENV,redirect_gateway=0 +>CLIENT:ENV,END +TITLE OpenVPN 2.3.4 i586-pc-linux-gnu [SSL (OpenSSL)] [LZO] [EPOLL] [PKCS11] [MH] [IPv6] built on Jun 26 2017 +TIME Wed Apr 17 03:31:06 2019 1555439466 +HEADER CLIENT_LIST Common Name Real Address Virtual Address Bytes Received Bytes Sent Connected Since Connected Since (time_t) Username +CLIENT_LIST pepehome 1.2.3.4:44347 10.9.0.5 6043 5661 Wed Apr 17 03:31:05 2019 1555439465 pepe +HEADER ROUTING_TABLE Virtual Address Common Name Real Address Last Ref Last Ref (time_t) +ROUTING_TABLE 10.9.0.5 pepehome 1.2.3.4:44347 Wed Apr 17 03:31:06 2019 1555439466 +GLOBAL_STATS Max bcast/mcast queue length 0 +END diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/client/testdata/version.txt b/src/go/collectors/go.d.plugin/modules/openvpn/client/testdata/version.txt new file mode 100644 index 000000000..e525876d8 --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/client/testdata/version.txt @@ -0,0 +1,3 @@ +OpenVPN Version: OpenVPN 2.3.4 i586-pc-linux-gnu [SSL (OpenSSL)] [LZO] [EPOLL] [PKCS11] [MH] [IPv6] built on Jun 26 2017 +Management Version: 1 +END diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/client/types.go b/src/go/collectors/go.d.plugin/modules/openvpn/client/types.go new file mode 100644 index 000000000..a0a283028 --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/client/types.go @@ -0,0 +1,28 @@ +// SPDX-License-Identifier: GPL-3.0-or-later + +package client + +type LoadStats struct { + NumOfClients int64 + BytesIn int64 + BytesOut int64 +} + +type Version struct { + Major int64 + Minor int64 + Patch int64 + Management int64 +} + +type Users []User + +type User struct { + CommonName string + RealAddress string + VirtualAddress string + BytesReceived int64 + BytesSent int64 + ConnectedSince int64 + Username string +} diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/collect.go b/src/go/collectors/go.d.plugin/modules/openvpn/collect.go new file mode 100644 index 000000000..180fae3bd --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/collect.go @@ -0,0 +1,90 @@ +// SPDX-License-Identifier: GPL-3.0-or-later + +package openvpn + +import ( + "fmt" + "time" +) + +func (o *OpenVPN) collect() (map[string]int64, error) { + var err error + + if err := o.client.Connect(); err != nil { + return nil, err + } + defer func() { _ = o.client.Disconnect() }() + + mx := make(map[string]int64) + + if err = o.collectLoadStats(mx); err != nil { + return nil, err + } + + if o.perUserMatcher != nil { + if err = o.collectUsers(mx); err != nil { + return nil, err + } + } + + return mx, nil +} + +func (o *OpenVPN) collectLoadStats(mx map[string]int64) error { + stats, err := o.client.LoadStats() + if err != nil { + return err + } + + mx["clients"] = stats.NumOfClients + mx["bytes_in"] = stats.BytesIn + mx["bytes_out"] = stats.BytesOut + return nil +} + +func (o *OpenVPN) collectUsers(mx map[string]int64) error { + users, err := o.client.Users() + if err != nil { + return err + } + + now := time.Now().Unix() + var name string + + for _, user := range users { + if user.Username == "UNDEF" { + name = user.CommonName + } else { + name = user.Username + } + + if !o.perUserMatcher.MatchString(name) { + continue + } + if !o.collectedUsers[name] { + o.collectedUsers[name] = true + if err := o.addUserCharts(name); err != nil { + o.Warning(err) + } + } + mx[name+"_bytes_received"] = user.BytesReceived + mx[name+"_bytes_sent"] = user.BytesSent + mx[name+"_connection_time"] = now - user.ConnectedSince + } + return nil +} + +func (o *OpenVPN) addUserCharts(userName string) error { + cs := userCharts.Copy() + + for _, chart := range *cs { + chart.ID = fmt.Sprintf(chart.ID, userName) + chart.Fam = fmt.Sprintf(chart.Fam, userName) + + for _, dim := range chart.Dims { + dim.ID = fmt.Sprintf(dim.ID, userName) + } + chart.MarkNotCreated() + } + return o.charts.Add(*cs...) +} diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/config_schema.json b/src/go/collectors/go.d.plugin/modules/openvpn/config_schema.json new file mode 100644 index 000000000..527a06abe --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/config_schema.json @@ -0,0 +1,102 @@ +{ + "jsonSchema": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OpenVPN collector configuration.", + "type": "object", + "properties": { + "update_every": { + "title": "Update every", + "description": "Data collection interval, measured in seconds.", + "type": "integer", + "minimum": 1, + "default": 1 + }, + "address": { + "title": "Address", + "description": "The IP address and port where the OpenVPN [Management Interface](https://openvpn.net/community-resources/management-interface/) listens for connections.", + "type": "string", + "default": "127.0.0.1:123" + }, + "timeout": { + "title": "Timeout", + "description": "Timeout for establishing a connection and communication (reading and writing) in seconds.", + "type": "number", + "minimum": 0.5, + "default": 1 + }, + "per_user_stats": { + "title": "User selector", + "description": "Configuration for monitoring specific users. If left empty, no user stats will be collected.", + "type": [ + "object", + "null" + ], + "properties": { + "includes": { + "title": "Include", + "description": "Include users whose usernames match any of the specified inclusion [patterns](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/matcher#readme).", + "type": [ + "array", + "null" + ], + "items": { + "title": "Username pattern", + "type": "string" + }, + "uniqueItems": true + }, + "excludes": { + "title": "Exclude", + "description": "Exclude users whose usernames match any of the specified exclusion [patterns](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/matcher#readme).", + "type": [ + "array", + "null" + ], + "items": { + "title": "Username pattern", + "type": "string" + }, + "uniqueItems": true + } + } + } + }, + "required": [ + "address" + ], + "additionalProperties": false, + "patternProperties": { + "^name$": {} + } + }, + "uiSchema": { + "uiOptions": { + "fullPage": true + }, + "timeout": { + "ui:help": "Accepts decimals for precise control (e.g., type 1.5 for 1.5 seconds)." + }, + "per_user_stats": { + "ui:help": "The logic for inclusion and exclusion is as follows: `(include1 OR include2) AND !(exclude1 OR exclude2)`." + }, + "ui:flavour": "tabs", + "ui:options": { + "tabs": [ + { + "title": "Base", + "fields": [ + "update_every", + "address", + "timeout" + ] + }, + { + "title": "User stats", + "fields": [ + "per_user_stats" + ] + } + ] + } + } +} diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/init.go b/src/go/collectors/go.d.plugin/modules/openvpn/init.go new file mode 100644 index 000000000..cba0c86e2 --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/init.go @@ -0,0 +1,30 @@ +// SPDX-License-Identifier: GPL-3.0-or-later + +package openvpn + +import ( + "github.com/netdata/netdata/go/go.d.plugin/modules/openvpn/client" + "github.com/netdata/netdata/go/go.d.plugin/pkg/matcher" + "github.com/netdata/netdata/go/go.d.plugin/pkg/socket" +) + +func (o *OpenVPN) validateConfig() error { + return nil +} + +func (o *OpenVPN) initPerUserMatcher() (matcher.Matcher, error) { + if o.PerUserStats.Empty() { + return nil, nil + } + return o.PerUserStats.Parse() +} + +func (o *OpenVPN) initClient() *client.Client { + config := socket.Config{ + Address: o.Address, + ConnectTimeout: o.Timeout.Duration(), + ReadTimeout: o.Timeout.Duration(), + WriteTimeout: o.Timeout.Duration(), + } + return &client.Client{Client: socket.New(config)} +} diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/integrations/openvpn.md b/src/go/collectors/go.d.plugin/modules/openvpn/integrations/openvpn.md new file mode 100644 index 000000000..6788f21ed --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/integrations/openvpn.md @@ -0,0 +1,223 @@ +<!--startmeta +custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/go/collectors/go.d.plugin/modules/openvpn/README.md" +meta_yaml: "https://github.com/netdata/netdata/edit/master/src/go/collectors/go.d.plugin/modules/openvpn/metadata.yaml" +sidebar_label: "OpenVPN" +learn_status: "Published" +learn_rel_path: "Collecting Metrics/VPNs" +most_popular: False +message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE" +endmeta--> + +# OpenVPN + + +<img src="https://netdata.cloud/img/openvpn.svg" width="150"/> + + +Plugin: go.d.plugin +Module: openvpn + +<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" /> + +## Overview + +This collector monitors OpenVPN servers. + +It uses OpenVPN [Management Interface](https://openvpn.net/community-resources/management-interface/) to collect metrics. + + + + +This collector is supported on all platforms. + +This collector supports collecting metrics from multiple instances of this integration, including remote instances. + + +### Default Behavior + +#### Auto-Detection + +This integration doesn't support auto-detection. + +#### Limits + +The default configuration for this integration does not impose any limits on data collection. + +#### Performance Impact + +The default configuration for this integration is not expected to impose a significant performance impact on the system. + + +## Metrics + +Metrics grouped by *scope*. + +The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels. + + + +### Per OpenVPN instance + +These metrics refer to the entire monitored application. + +This scope has no labels. + +Metrics: + +| Metric | Dimensions | Unit | +|:------|:----------|:----| +| openvpn.active_clients | clients | clients | +| openvpn.total_traffic | in, out | kilobits/s | + +### Per user + +These metrics refer to the VPN user. + +Labels: + +| Label | Description | +|:-----------|:----------------| +| username | VPN username | + +Metrics: + +| Metric | Dimensions | Unit | +|:------|:----------|:----| +| openvpn.user_traffic | in, out | kilobits/s | +| openvpn.user_connection_time | time | seconds | + + + +## Alerts + +There are no alerts configured by default for this integration. + + +## Setup + +### Prerequisites + +#### Enable in go.d.conf. + +This collector is disabled by default. You need to explicitly enable it in [go.d.conf](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/config/go.d.conf). + +From the documentation for the OpenVPN Management Interface: +> Currently, the OpenVPN daemon can at most support a single management client any one time. + +It is disabled to not break other tools which use `Management Interface`. + + + +### Configuration + +#### File + +The configuration file name for this integration is `go.d/openvpn.conf`. + + +You can edit the configuration file using the `edit-config` script from the +Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration.md#the-netdata-config-directory). + +```bash +cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata +sudo ./edit-config go.d/openvpn.conf +``` +#### Options + +The following options can be defined globally: update_every, autodetection_retry. + + +<details><summary>Config options</summary> + +| Name | Description | Default | Required | +|:----|:-----------|:-------|:--------:| +| update_every | Data collection frequency. | 1 | no | +| autodetection_retry | Recheck interval in seconds. Zero means no recheck will be scheduled. | 0 | no | +| address | Server address in IP:PORT format. | 127.0.0.1:7505 | yes | +| timeout | Connection, read, and write timeout duration in seconds. The timeout includes name resolution. | 1 | no | +| per_user_stats | User selector. Determines which user metrics will be collected. | | no | + +</details> + +#### Examples + +##### Basic + +A basic example configuration. + +<details><summary>Config</summary> + +```yaml +jobs: + - name: local + address: 127.0.0.1:7505 + +``` +</details> + +##### With user metrics + +Collect metrics of all users. + +<details><summary>Config</summary> + +```yaml +jobs: + - name: local + address: 127.0.0.1:7505 + per_user_stats: + includes: + - "* *" + +``` +</details> + +##### Multi-instance + +> **Note**: When you define multiple jobs, their names must be unique. + +Collecting metrics from local and remote instances. + + +<details><summary>Config</summary> + +```yaml +jobs: + - name: local + address: 127.0.0.1:7505 + + - name: remote + address: 203.0.113.0:7505 + +``` +</details> + + + +## Troubleshooting + +### Debug Mode + +To troubleshoot issues with the `openvpn` collector, run the `go.d.plugin` with the debug option enabled. The output +should give you clues as to why the collector isn't working. + +- Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on + your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`. + + ```bash + cd /usr/libexec/netdata/plugins.d/ + ``` + +- Switch to the `netdata` user. + + ```bash + sudo -u netdata -s + ``` + +- Run the `go.d.plugin` to debug the collector: + + ```bash + ./go.d.plugin -d -m openvpn + ``` + + diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/metadata.yaml b/src/go/collectors/go.d.plugin/modules/openvpn/metadata.yaml new file mode 100644 index 000000000..b1f583c9b --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/metadata.yaml @@ -0,0 +1,177 @@ +plugin_name: go.d.plugin +modules: + - meta: + id: collector-go.d.plugin-openvpn + plugin_name: go.d.plugin + module_name: openvpn + monitored_instance: + name: OpenVPN + link: https://openvpn.net/ + icon_filename: openvpn.svg + categories: + - data-collection.vpns + keywords: + - openvpn + - vpn + related_resources: + integrations: + list: [] + info_provided_to_referring_integrations: + description: "" + most_popular: false + overview: + data_collection: + metrics_description: | + This collector monitors OpenVPN servers. + + It uses OpenVPN [Management Interface](https://openvpn.net/community-resources/management-interface/) to collect metrics. + method_description: "" + supported_platforms: + include: [] + exclude: [] + multi_instance: true + additional_permissions: + description: "" + default_behavior: + auto_detection: + description: "" + limits: + description: "" + performance_impact: + description: "" + setup: + prerequisites: + list: + - title: Enable in go.d.conf. + description: | + This collector is disabled by default. You need to explicitly enable it in [go.d.conf](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/config/go.d.conf). + + From the documentation for the OpenVPN Management Interface: + > Currently, the OpenVPN daemon can at most support a single management client any one time. + + It is disabled to not break other tools which use `Management Interface`. + configuration: + file: + name: go.d/openvpn.conf + options: + description: | + The following options can be defined globally: update_every, autodetection_retry. + folding: + title: Config options + enabled: true + list: + - name: update_every + description: Data collection frequency. + default_value: 1 + required: false + - name: autodetection_retry + description: Recheck interval in seconds. Zero means no recheck will be scheduled. + default_value: 0 + required: false + - name: address + description: Server address in IP:PORT format. + default_value: 127.0.0.1:7505 + required: true + - name: timeout + description: Connection, read, and write timeout duration in seconds. The timeout includes name resolution. + default_value: 1 + required: false + - name: per_user_stats + description: User selector. Determines which user metrics will be collected. + default_value: "" + required: false + details: | + Metrics of users matching the selector will be collected. + + - Logic: (pattern1 OR pattern2) AND !(pattern3 or pattern4) + - Pattern syntax: [matcher](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/matcher#supported-format). + - Syntax: + + ```yaml + per_user_stats: + includes: + - pattern1 + - pattern2 + excludes: + - pattern3 + - pattern4 + ``` + examples: + folding: + title: Config + enabled: true + list: + - name: Basic + description: A basic example configuration. + config: | + jobs: + - name: local + address: 127.0.0.1:7505 + - name: With user metrics + description: Collect metrics of all users. + config: | + jobs: + - name: local + address: 127.0.0.1:7505 + per_user_stats: + includes: + - "* *" + - name: Multi-instance + description: | + > **Note**: When you define multiple jobs, their names must be unique. + + Collecting metrics from local and remote instances. + config: | + jobs: + - name: local + address: 127.0.0.1:7505 + + - name: remote + address: 203.0.113.0:7505 + troubleshooting: + problems: + list: [] + alerts: [] + metrics: + folding: + title: Metrics + enabled: false + description: "" + availability: [] + scopes: + - name: global + description: These metrics refer to the entire monitored application. + labels: [] + metrics: + - name: openvpn.active_clients + description: Total Number Of Active Clients + unit: clients + chart_type: line + dimensions: + - name: clients + - name: openvpn.total_traffic + description: Total Traffic + unit: kilobits/s + chart_type: area + dimensions: + - name: in + - name: out + - name: user + description: These metrics refer to the VPN user. + labels: + - name: username + description: VPN username + metrics: + - name: openvpn.user_traffic + description: User Traffic + unit: kilobits/s + chart_type: area + dimensions: + - name: in + - name: out + - name: openvpn.user_connection_time + description: User Connection Time + unit: seconds + chart_type: line + dimensions: + - name: time diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/openvpn.go b/src/go/collectors/go.d.plugin/modules/openvpn/openvpn.go new file mode 100644 index 000000000..0d4fbe419 --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/openvpn.go @@ -0,0 +1,127 @@ +// SPDX-License-Identifier: GPL-3.0-or-later + +package openvpn + +import ( + _ "embed" + "time" + + "github.com/netdata/netdata/go/go.d.plugin/agent/module" + "github.com/netdata/netdata/go/go.d.plugin/modules/openvpn/client" + "github.com/netdata/netdata/go/go.d.plugin/pkg/matcher" + "github.com/netdata/netdata/go/go.d.plugin/pkg/socket" + "github.com/netdata/netdata/go/go.d.plugin/pkg/web" +) + +//go:embed "config_schema.json" +var configSchema string + +func init() { + module.Register("openvpn", module.Creator{ + JobConfigSchema: configSchema, + Create: func() module.Module { return New() }, + }) +} + +func New() *OpenVPN { + return &OpenVPN{ + Config: Config{ + Address: "127.0.0.1:7505", + Timeout: web.Duration(time.Second), + }, + + charts: charts.Copy(), + collectedUsers: make(map[string]bool), + } +} + +type Config struct { + UpdateEvery int `yaml:"update_every" json:"update_every"` + Address string `yaml:"address" json:"address"` + Timeout web.Duration `yaml:"timeout" json:"timeout"` + PerUserStats matcher.SimpleExpr `yaml:"per_user_stats" json:"per_user_stats"` +} + +type ( + OpenVPN struct { + module.Base + Config `yaml:",inline" json:""` + + charts *Charts + + client openVPNClient + + collectedUsers map[string]bool + perUserMatcher matcher.Matcher + } + openVPNClient interface { + socket.Client + Version() (*client.Version, error) + LoadStats() (*client.LoadStats, error) + Users() (client.Users, error) + } +) + +func (o *OpenVPN) Configuration() any { + return o.Config +} + +func (o *OpenVPN) Init() error { + if err := o.validateConfig(); err != nil { + o.Error(err) + return err + } + + m, err := o.initPerUserMatcher() + if err != nil { + o.Error(err) + return err + } + o.perUserMatcher = m + + o.client = o.initClient() + + o.Infof("using address: %s, timeout: %s", o.Address, o.Timeout) + + return nil +} + +func (o *OpenVPN) Check() error { + if err := o.client.Connect(); err != nil { + o.Error(err) + return err + } + defer func() { _ = o.client.Disconnect() }() + + ver, err := o.client.Version() + if err != nil { + o.Error(err) + o.Cleanup() + return err + } + + o.Infof("connected to OpenVPN v%d.%d.%d, Management v%d", ver.Major, ver.Minor, ver.Patch, ver.Management) + + return nil +} + +func (o *OpenVPN) Charts() *Charts { return o.charts } + +func (o *OpenVPN) Collect() map[string]int64 { + mx, err := o.collect() + if err != nil { + o.Error(err) + } + + if len(mx) == 0 { + return nil + } + return mx +} + +func (o *OpenVPN) Cleanup() { + if o.client == nil { + return + } + _ = o.client.Disconnect() +} diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/openvpn_test.go b/src/go/collectors/go.d.plugin/modules/openvpn/openvpn_test.go new file mode 100644 index 000000000..267713b68 --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/openvpn_test.go @@ -0,0 +1,153 @@ +// SPDX-License-Identifier: GPL-3.0-or-later + +package openvpn + +import ( + "os" + "testing" + + "github.com/netdata/netdata/go/go.d.plugin/agent/module" + "github.com/netdata/netdata/go/go.d.plugin/modules/openvpn/client" + "github.com/netdata/netdata/go/go.d.plugin/pkg/matcher" + "github.com/netdata/netdata/go/go.d.plugin/pkg/socket" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +var ( + dataConfigJSON, _ = os.ReadFile("testdata/config.json") + dataConfigYAML, _ = os.ReadFile("testdata/config.yaml") +) + +func Test_testDataIsValid(t *testing.T) { + for name, data := range map[string][]byte{ + "dataConfigJSON": dataConfigJSON, + "dataConfigYAML": dataConfigYAML, + } { + require.NotNil(t, data, name) + } +} + +func TestOpenVPN_ConfigurationSerialize(t *testing.T) { + module.TestConfigurationSerialize(t, &OpenVPN{}, dataConfigJSON, dataConfigYAML) +} + +func TestOpenVPN_Init(t *testing.T) { + assert.NoError(t, New().Init()) +} + +func TestOpenVPN_Check(t *testing.T) { + job := New() + + require.NoError(t, job.Init()) + job.client = prepareMockOpenVPNClient() + require.NoError(t, job.Check()) +} + +func TestOpenVPN_Charts(t *testing.T) { + assert.NotNil(t, New().Charts()) +} + +func TestOpenVPN_Cleanup(t *testing.T) { + job := New() + + assert.NotPanics(t, job.Cleanup) + require.NoError(t, job.Init()) + job.client = prepareMockOpenVPNClient() + require.NoError(t, job.Check()) + job.Cleanup() +} + +func TestOpenVPN_Collect(t *testing.T) { + job := New() + + require.NoError(t, job.Init()) + job.perUserMatcher = matcher.TRUE() + job.client = prepareMockOpenVPNClient() + require.NoError(t, job.Check()) + + expected := map[string]int64{ + "bytes_in": 1, + "bytes_out": 1, + "clients": 1, + "name_bytes_received": 1, + "name_bytes_sent": 2, + } + + mx := job.Collect() + require.NotNil(t, mx) + delete(mx, "name_connection_time") + assert.Equal(t, expected, mx) +} + +func TestOpenVPN_Collect_UNDEFUsername(t *testing.T) { + job := New() + + require.NoError(t, job.Init()) + job.perUserMatcher = matcher.TRUE() + cl := prepareMockOpenVPNClient() + cl.users = testUsersUNDEF + job.client = cl + require.NoError(t, job.Check()) + + expected := map[string]int64{ + "bytes_in": 1, + "bytes_out": 1, + "clients": 1, + "common_name_bytes_received": 1, + "common_name_bytes_sent": 2, + } + + mx := job.Collect() + require.NotNil(t, mx) + delete(mx, "common_name_connection_time") + assert.Equal(t, expected, mx) +} + +func prepareMockOpenVPNClient() *mockOpenVPNClient { + return &mockOpenVPNClient{ + version: testVersion, + loadStats: testLoadStats, + users: testUsers, + } +} + +type mockOpenVPNClient struct { + version client.Version + loadStats client.LoadStats + users client.Users +} + +func (m *mockOpenVPNClient) Connect() error { return nil } +func (m *mockOpenVPNClient) Disconnect() error { return nil } +func (m *mockOpenVPNClient) Version() (*client.Version, error) { return &m.version, nil } +func (m *mockOpenVPNClient) LoadStats() (*client.LoadStats, error) { return &m.loadStats, nil } +func (m *mockOpenVPNClient) Users() (client.Users, error) { return m.users, nil } +func (m *mockOpenVPNClient) Command(_ string, _ socket.Processor) error { + // mocks are done on the individual commands. e.g. in Version() below + panic("should be called in the mock") +} + +var ( + testVersion = client.Version{Major: 1, Minor: 1, Patch: 1, Management: 1} + testLoadStats = client.LoadStats{NumOfClients: 1, BytesIn: 1, BytesOut: 1} + testUsers = client.Users{{ + CommonName: "common_name", + RealAddress: "1.2.3.4:4321", + VirtualAddress: "1.2.3.4", + BytesReceived: 1, + BytesSent: 2, + ConnectedSince: 3, + Username: "name", + }} + testUsersUNDEF = client.Users{{ + CommonName: "common_name", + RealAddress: "1.2.3.4:4321", + VirtualAddress: "1.2.3.4", + BytesReceived: 1, + BytesSent: 2, + ConnectedSince: 3, + Username: "UNDEF", + }} +) diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/testdata/config.json b/src/go/collectors/go.d.plugin/modules/openvpn/testdata/config.json new file mode 100644 index 000000000..30411ebf3 --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/testdata/config.json @@ -0,0 +1,13 @@ +{ + "update_every": 123, + "address": "ok", + "timeout": 123.123, + "per_user_stats": { + "includes": [ + "ok" + ], + "excludes": [ + "ok" + ] + } +} diff --git a/src/go/collectors/go.d.plugin/modules/openvpn/testdata/config.yaml b/src/go/collectors/go.d.plugin/modules/openvpn/testdata/config.yaml new file mode 100644 index 000000000..22296ce56 --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/openvpn/testdata/config.yaml @@ -0,0 +1,8 @@ +update_every: 123 +address: "ok" +timeout: 123.123 +per_user_stats: + includes: + - "ok" + excludes: + - "ok" |