Back to godoc.org
github.com/mdlayher/vsock

package vsock

v0.0.0 (7ad3638)
Latest Go to latest
Published: May 8, 2020 | License: MIT | Module: github.com/mdlayher/vsock

Overview

Package vsock provides access to Linux VM sockets (AF_VSOCK) for communication between a hypervisor and its virtual machines.

The types in this package implement interfaces provided by package net and may be used in applications that expect a net.Listener or net.Conn.

- *Addr implements net.Addr
- *Conn implements net.Conn
- *Listener implements net.Listener

Go version support

This package supports varying levels of functionality depending on the version of Go used during compilation. The Listener and Conn types produced by this package are backed by non-blocking I/O, in order to integrate with Go's runtime network poller in Go 1.11+. Additional functionality is available starting in Go 1.12+.

Go 1.12+ (recommended):

- *Listener:
  - Accept blocks until a connection is received
  - Close can interrupt Accept and make it return a permanent error
  - SetDeadline can set timeouts which can interrupt Accept and make it return a
    temporary error
- *Conn:
  - SetDeadline family of methods are fully supported
  - CloseRead and CloseWrite can close the reading or writing sides of a
    Conn, respectively
  - SyscallConn provides access to raw network control/read/write functionality

Go 1.11 (not recommended):

- *Listener:
  - Accept is non-blocking and should be called in a loop, checking for
    net.Error.Temporary() == true and sleeping for a short period to avoid wasteful
    CPU cycle consumption
  - Close makes Accept return a permanent error on the next loop iteration
  - SetDeadline is not supported and will always return an error
- *Conn:
  - SetDeadline family of methods are fully supported
  - CloseRead and CloseWrite are not supported and will always return an error
  - SyscallConn is not supported and will always return an error

Go 1.10 (not recommended):

- *Listener:
  - Accept blocks until a connection is received
  - Close cannot unblock Accept
  - SetDeadline is not supported and will always return an error
- *Conn:
  - SetDeadline is not supported and will always return an error
  - CloseRead and CloseWrite are not supported and will always return an error
  - SyscallConn is not supported and will always return an error

Stability

At this time, package vsock is in a pre-v1.0.0 state. Changes are being made which may impact the exported API of this package and others in its ecosystem.

If you depend on this package in your application, please use Go modules when building your application.

Index

Constants

const (
	// Hypervisor specifies that a socket should communicate with the hypervisor
	// process.
	Hypervisor = 0x0

	// Host specifies that a socket should communicate with processes other than
	// the hypervisor on the host machine.
	Host = 0x2
)

func ContextID

func ContextID() (uint32, error)

ContextID retrieves the local VM sockets context ID for this system. ContextID can be used to directly determine if a system is capable of using VM sockets.

If the kernel module is unavailable, access to the kernel module is denied, or VM sockets are unsupported on this system, it returns an error.

type Addr

type Addr struct {
	ContextID uint32
	Port      uint32
}

An Addr is the address of a VM sockets endpoint.

func (*Addr) Network

func (a *Addr) Network() string

Network returns the address's network name, "vsock".

func (*Addr) String

func (a *Addr) String() string

String returns a human-readable representation of Addr, and indicates if ContextID is meant to be used for a hypervisor, host, VM, etc.

type Conn

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

A Conn is a VM sockets implementation of a net.Conn.

func Dial

func Dial(contextID, port uint32) (*Conn, error)

Dial dials a connection-oriented net.Conn to a VM sockets server. The contextID and port parameters specify the address of the server.

If dialing a connection from the hypervisor to a virtual machine, the VM's context ID should be specified.

If dialing from a VM to the hypervisor, Hypervisor should be used to communicate with the hypervisor process, or Host should be used to communicate with other processes on the host machine.

When the connection is no longer needed, Close must be called to free resources.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) CloseRead

func (c *Conn) CloseRead() error

CloseRead shuts down the reading side of the VM sockets connection. Most callers should just use Close.

CloseRead only works with Go 1.12+.

func (*Conn) CloseWrite

func (c *Conn) CloseWrite() error

CloseWrite shuts down the writing side of the VM sockets connection. Most callers should just use Close.

CloseWrite only works with Go 1.12+.

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

LocalAddr returns the local network address. The Addr returned is shared by all invocations of LocalAddr, so do not modify it.

func (*Conn) Read

func (c *Conn) Read(b []byte) (int, error)

Read implements the net.Conn Read method.

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr returns the remote network address. The Addr returned is shared by all invocations of RemoteAddr, so do not modify it.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline implements the net.Conn SetDeadline method.

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline implements the net.Conn SetReadDeadline method.

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements the net.Conn SetWriteDeadline method.

func (*Conn) SyscallConn

func (c *Conn) SyscallConn() (syscall.RawConn, error)

SyscallConn returns a raw network connection. This implements the syscall.Conn interface.

func (*Conn) Write

func (c *Conn) Write(b []byte) (int, error)

Write implements the net.Conn Write method.

type Listener

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

A Listener is a VM sockets implementation of a net.Listener.

func Listen

func Listen(port uint32) (*Listener, error)

Listen opens a connection-oriented net.Listener for incoming VM sockets connections. The port parameter specifies the port for the Listener.

To allow the server to assign a port automatically, specify 0 for port. The address of the server can be retrieved using the Addr method.

When the Listener is no longer needed, Close must be called to free resources.

func (*Listener) Accept

func (l *Listener) Accept() (net.Conn, error)

Accept implements the Accept method in the net.Listener interface; it waits for the next call and returns a generic net.Conn. The returned net.Conn will always be of type *Conn.

func (*Listener) Addr

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

Addr returns the listener's network address, a *Addr. The Addr returned is shared by all invocations of Addr, so do not modify it.

func (*Listener) Close

func (l *Listener) Close() error

Close stops listening on the VM sockets address. Already Accepted connections are not closed.

func (*Listener) SetDeadline

func (l *Listener) SetDeadline(t time.Time) error

SetDeadline sets the deadline associated with the listener. A zero time value disables the deadline.

SetDeadline only works with Go 1.12+.

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
f or F : Jump to identifier