Documentation
¶
Index ¶
- func ListenAndServe(laddr string, handler IncomingConnHandler) error
- type ByteCountEvent
- type EchoEvent
- type ErrorFromServer
- type Event
- type HoldEvent
- type IncomingConn
- type IncomingConnHandler
- type IncomingConnHandlerFunc
- type MalformedEvent
- type MgmtClient
- func (c *MgmtClient) HoldRelease() error
- func (c *MgmtClient) LatestState() (*StateEvent, error)
- func (c *MgmtClient) LatestStatus(statusFormat StatusFormat) ([][]byte, error)
- func (c *MgmtClient) Pid() (int, error)
- func (c *MgmtClient) SendPassword(pass string) ([]byte, error)
- func (c *MgmtClient) SendSignal(name string) error
- func (c *MgmtClient) SetByteCountEvents(interval time.Duration) error
- func (c *MgmtClient) SetEchoEvents(on bool) error
- func (c *MgmtClient) SetStateEvents(on bool) error
- type MgmtListener
- type StateEvent
- type StatusFormat
- type UnknownEvent
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)
type ErrorFromServer ¶
type ErrorFromServer []byte
func (ErrorFromServer) Error ¶
func (err ErrorFromServer) Error() string
func (ErrorFromServer) String ¶
func (err ErrorFromServer) 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()
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) RemotePort ¶
func (e *StateEvent) RemotePort() string
RemotePort returns the port of the remote 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
Source Files