management

package
v0.0.0-...-f83380f Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 14, 2024 License: GPL-3.0 Imports: 7 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ListenAndServe

func ListenAndServe(laddr string, handler IncomingConnHandler) error

ListenAndServe creates a MgmtListener for the given listen address and then calls AcceptAndServe on it.

This is just a convenience wrapper. See the AcceptAndServe method for more details. Just as with AcceptAndServe, this function does not return except on error; in addition to the error cases handled by AcceptAndServe, this function may also fail if the listen socket cannot be established in the first place.

Types

type ByteCountEvent

type ByteCountEvent struct {
	// contains filtered or unexported fields
}

ByteCountEvent represents a periodic snapshot of data transfer in bytes on a VPN connection.

For OpenVPN *servers*, events are emitted for each client and the method ClientId identifies thet client.

For other OpenVPN modes, events are emitted only once per interval for the single connection managed by the target process, and ClientId returns the empty string.

func (*ByteCountEvent) BytesIn

func (e *ByteCountEvent) BytesIn() int

func (*ByteCountEvent) BytesOut

func (e *ByteCountEvent) BytesOut() int

func (*ByteCountEvent) ClientId

func (e *ByteCountEvent) ClientId() string

func (*ByteCountEvent) String

func (e *ByteCountEvent) String() string

type EchoEvent

type EchoEvent struct {
	// contains filtered or unexported fields
}

EchoEvent is emitted by an OpenVPN process running in client mode when an "echo" command is pushed to it by the server it has connected to.

The format of the echo message is free-form, since this message type is intended to pass application-specific data from the server-side config into whatever client is consuming the management prototcol.

This event is emitted only if the management client has turned on events of this type using client.SetEchoEvents(true)

func (*EchoEvent) Message

func (e *EchoEvent) Message() string

func (*EchoEvent) RawTimestamp

func (e *EchoEvent) RawTimestamp() string

func (*EchoEvent) String

func (e *EchoEvent) String() string

type ErrorFromServer

type ErrorFromServer []byte

func (ErrorFromServer) Error

func (err ErrorFromServer) Error() string

func (ErrorFromServer) String

func (err ErrorFromServer) String() string

type Event

type Event interface {
	String() string
}

type HoldEvent

type HoldEvent struct {
	// contains filtered or unexported fields
}

HoldEvent is a notification that the OpenVPN process is in a management hold and will not continue connecting until the hold is released, e.g. by calling client.HoldRelease()

func (*HoldEvent) String

func (e *HoldEvent) String() string

type IncomingConn

type IncomingConn struct {
	// contains filtered or unexported fields
}

func (IncomingConn) Close

func (ic IncomingConn) Close() error

Close abruptly closes the socket connected to the OpenVPN process.

This is a rather abrasive way to close the channel, intended for rejecting unwanted incoming clients that may or may not speak the OpenVPN protocol.

Once communication is accepted and established, it is generally better to close the connection gracefully using commands on the client returned from Open.

func (IncomingConn) Open

func (ic IncomingConn) Open(eventCh chan<- Event) *MgmtClient

Open initiates communication with the connected OpenVPN process, and establishes the channel on which events will be delivered.

See the documentation for NewClient for discussion about the requirements for eventCh.

type IncomingConnHandler

type IncomingConnHandler interface {
	ServeOpenVPNMgmt(IncomingConn)
}

type IncomingConnHandlerFunc

type IncomingConnHandlerFunc func(IncomingConn)

IncomingConnHandlerFunc is an adapter to allow the use of ordinary functions as connection handlers.

Given a function with the appropriate signature, IncomingConnHandlerFunc(f) is an IncomingConnHandler that calls f.

func (IncomingConnHandlerFunc) ServeOpenVPNMgmt

func (f IncomingConnHandlerFunc) ServeOpenVPNMgmt(i IncomingConn)

type MalformedEvent

type MalformedEvent struct {
	// contains filtered or unexported fields
}

MalformedEvent represents a message from the OpenVPN process that is presented as an event but does not comply with the expected event syntax.

Events of this type should never be seen but robust callers will accept and ignore them, possibly generating some kind of debugging message.

One reason for potentially seeing events of this type is when the target program is actually not an OpenVPN process at all, but in fact this client has been connected to a different sort of server by mistake.

func (*MalformedEvent) String

func (e *MalformedEvent) String() string

type MgmtClient

type MgmtClient struct {
	// contains filtered or unexported fields
}

MgmtClient .

func Dial

func Dial(addr string, eventCh chan<- Event) (*MgmtClient, error)

Dial is a convenience wrapper around NewClient that handles the common case of opening an TCP/IP socket to an OpenVPN management port and creating a client for it.

See the NewClient docs for discussion about the requirements for eventCh.

OpenVPN will create a suitable management port if launched with the following command line option:

--management <ipaddr> <port>

Address may an IPv4 address, an IPv6 address, or a hostname that resolves to either of these, followed by a colon and then a port number.

When running on Unix systems it's possible to instead connect to a Unix domain socket. To do this, pass an absolute path to the socket as the target address, having run OpenVPN with the following options:

--management /path/to/socket unix

func NewClient

func NewClient(conn io.ReadWriter, eventCh chan<- Event) *MgmtClient

NewClient creates a new MgmtClient that communicates via the given io.ReadWriter and emits events on the given channel.

eventCh should be a buffered channel with a sufficient buffer depth such that it cannot be filled under the expected event volume. Event volume depends on which events are enabled and how they are configured; some of the event-enabling functions have further discussion how frequently events are likely to be emitted, but the caller should also factor in how long its own event *processing* will take, since slow event processing will create back-pressure that could cause this buffer to fill faster.

It probably goes without saying given the previous paragraph, but the caller *must* constantly read events from eventCh to avoid its buffer becoming full. Events and replies are received on the same channel from OpenVPN, so if writing to eventCh blocks then this will also block responses from the client's various command methods.

eventCh will be closed to signal the closing of the client connection, whether due to graceful shutdown or to an error. In the case of error, a FatalEvent will be emitted on the channel as the last event before it is closed. Connection errors may also concurrently surface as error responses from the client's various command methods, should an error occur while we await a reply.

func (*MgmtClient) HoldRelease

func (c *MgmtClient) HoldRelease() error

HoldRelease instructs OpenVPN to release any management hold preventing it from proceeding, but to retain the state of the hold flag such that the daemon will hold again if it needs to reconnect for any reason.

OpenVPN can be instructed to activate a management hold on startup by running it with the following option:

--management-hold

Instructing OpenVPN to hold gives your client a chance to connect and do any necessary configuration before a connection proceeds, thus avoiding the problem of missed events.

When OpenVPN begins holding, or when a new management client connects while a hold is already in effect, a HoldEvent will be emitted on the event channel.

func (*MgmtClient) LatestState

func (c *MgmtClient) LatestState() (*StateEvent, error)

LatestState retrieves the most recent StateEvent from the server. This can either be used to poll the state or it can be used to determine the initial state after calling SetStateEvents(true) but before the first state event is delivered.

func (*MgmtClient) LatestStatus

func (c *MgmtClient) LatestStatus(statusFormat StatusFormat) ([][]byte, error)

LatestStatus retrieves the current daemon status information, in the same format as that produced by the OpenVPN --status directive.

func (*MgmtClient) Pid

func (c *MgmtClient) Pid() (int, error)

Pid retrieves the process id of the connected OpenVPN process.

func (*MgmtClient) SendPassword

func (c *MgmtClient) SendPassword(pass string) ([]byte, error)

func (*MgmtClient) SendSignal

func (c *MgmtClient) SendSignal(name string) error

SendSignal sends a signal to the OpenVPN process via the management channel. In effect this causes the OpenVPN process to send a signal to itself on our behalf.

OpenVPN accepts a subset of the usual UNIX signal names, including "SIGHUP", "SIGTERM", "SIGUSR1" and "SIGUSR2". See the OpenVPN manual page for the meaning of each.

Behavior is undefined if the given signal name is not entirely uppercase letters. In particular, including newlines in the string is likely to cause very unpredictable behavior.

func (*MgmtClient) SetByteCountEvents

func (c *MgmtClient) SetByteCountEvents(interval time.Duration) error

SetByteCountEvents either enables or disables ongoing asynchronous events for information on OpenVPN bandwidth usage.

When enabled, a ByteCountEvent will be emitted at given time interval, (which may only be whole seconds) describing how many bytes have been transferred in each direction See ByteCountEvent for more information.

Set the time interval to zero in order to disable byte count events.

func (*MgmtClient) SetEchoEvents

func (c *MgmtClient) SetEchoEvents(on bool) error

SetEchoEvents either enables or disables asynchronous events for "echo" commands sent from a remote server to our managed OpenVPN client.

When enabled, an EchoEvent will be emitted from the event channel each time the server sends an echo command. See EchoEvent for more information.

func (*MgmtClient) SetStateEvents

func (c *MgmtClient) SetStateEvents(on bool) error

SetStateEvents either enables or disables asynchronous events for changes in the OpenVPN connection state.

When enabled, a StateEvent will be emitted from the event channel each time the connection state changes. See StateEvent for more information on the event structure.

type MgmtListener

type MgmtListener struct {
	// contains filtered or unexported fields
}

MgmtListener accepts incoming connections from OpenVPN.

The primary way to instantiate this type is via the function Listen. See its documentation for more information.

func Listen

func Listen(laddr string) (*MgmtListener, error)

Listen opens a listen port and awaits incoming connections from OpenVPN processes.

OpenVPN will behave in this manner when launched with the following options:

--management ipaddr port --management-client

Note that in this case the terminology is slightly confusing, since from the standpoint of TCP/IP it is OpenVPN that is the client and our program that is the server, but once the connection is established the channel is indistinguishable from the situation where OpenVPN exposed a management *server* and we connected to it. Thus we still refer to our program as the "client" and OpenVPN as the "server" once the connection is established.

When running on Unix systems it's possible to instead listen on a Unix domain socket. To do this, pass an absolute path to the socket as the listen address, and then run OpenVPN with the following options:

--management /path/to/socket unix --management-client

func NewMgmtListener

func NewMgmtListener(l net.Listener) *MgmtListener

NewMgmtListener constructs a MgmtListener from an already-established net.Listener. In most cases it will be more convenient to use the function Listen.

func (*MgmtListener) Accept

func (l *MgmtListener) Accept() (*IncomingConn, error)

Accept waits for and returns the next connection.

func (*MgmtListener) Addr

func (l *MgmtListener) Addr() net.Addr

Addr returns the listener's network address.

func (*MgmtListener) Close

func (l *MgmtListener) Close() error

Close closes the listener. Any blocked Accept operations will be blocked and each will return an error.

func (*MgmtListener) Serve

func (l *MgmtListener) Serve(handler IncomingConnHandler) error

Serve will await new connections and call the given handler for each.

Serve does not return unless the listen port is closed; a non-nil error is always returned.

type StateEvent

type StateEvent struct {
	// contains filtered or unexported fields
}

StateEvent is a notification of a change of connection state. It can be used, for example, to detect if the OpenVPN connection has been interrupted and the OpenVPN process is attempting to reconnect.

func (*StateEvent) Description

func (e *StateEvent) Description() string

func (*StateEvent) LocalTunnelAddr

func (e *StateEvent) LocalTunnelAddr() string

LocalTunnelAddr returns the IP address of the local interface within the tunnel, as a string that can be parsed using net.ParseIP.

This field is only populated for events whose NewState returns either ASSIGN_IP or CONNECTED.

func (*StateEvent) NewState

func (e *StateEvent) NewState() string

func (*StateEvent) RawTimestamp

func (e *StateEvent) RawTimestamp() string

func (*StateEvent) RemoteAddr

func (e *StateEvent) RemoteAddr() string

RemoteAddr returns the non-tunnel IP address of the remote system that has connected to the local OpenVPN process.

This field is only populated for events whose NewState returns CONNECTED.

func (*StateEvent) String

func (e *StateEvent) String() string

type StatusFormat

type StatusFormat string

StatusFormat enum type

const (
	StatusFormatDefault StatusFormat = ""
	StatusFormatV3      StatusFormat = "3"
)

StatusFormatDefault openvpn default status format StatusFormatV3 openvpn version 3 status format

type UnknownEvent

type UnknownEvent struct {
	// contains filtered or unexported fields
}

UnknownEvent represents an event of a type that this package doesn't know about.

Future versions of this library may learn about new event types, so a caller should exercise caution when making use of events of this type to access unsupported behavior. Backward-compatibility is *not* guaranteed for events of this type.

func (*UnknownEvent) Body

func (e *UnknownEvent) Body() string

func (*UnknownEvent) String

func (e *UnknownEvent) String() string

func (*UnknownEvent) Type

func (e *UnknownEvent) Type() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL