vsock: github.com/mdlayher/vsock Index | Files | Directories

package vsock

import "github.com/mdlayher/vsock"

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 and below are not supported. The runtime network poller integration required by this package is not available in Go versions prior to Go 1.11. Unsupported versions of Go will produce a compilation error when trying to build this package.

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

Package Files

conn_linux.go doc.go fd_linux.go fd_linux_gteq_1.12.go listener_linux.go vsock.go

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 Uses

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 Uses

type Addr struct {
    ContextID uint32
    Port      uint32
}

An Addr is the address of a VM sockets endpoint.

func (*Addr) Network Uses

func (a *Addr) Network() string

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

func (*Addr) String Uses

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 Uses

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

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

func Dial Uses

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 Uses

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) CloseRead Uses

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 Uses

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 Uses

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 Uses

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

Read implements the net.Conn Read method.

func (*Conn) RemoteAddr Uses

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 Uses

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

SetDeadline implements the net.Conn SetDeadline method.

func (*Conn) SetReadDeadline Uses

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

SetReadDeadline implements the net.Conn SetReadDeadline method.

func (*Conn) SetWriteDeadline Uses

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

SetWriteDeadline implements the net.Conn SetWriteDeadline method.

func (*Conn) SyscallConn Uses

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

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

func (*Conn) Write Uses

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

Write implements the net.Conn Write method.

type Listener Uses

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

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

func Listen Uses

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 Uses

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 Uses

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 Uses

func (l *Listener) Close() error

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

func (*Listener) SetDeadline Uses

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+.

Directories

PathSynopsis
internal/vsutilPackage vsutil provides added functionality for package vsock-internal use.

Package vsock imports 9 packages (graph) and is imported by 5 packages. Updated 2019-05-20. Refresh now. Tools for package owners.