{ "content": [ { "type": "text", "text": "# vsock (man)\n\n## NAME\n\nvsock - Linux VSOCK address family\n\n## DESCRIPTION\n\nThe VSOCK address family facilitates communication between virtual machines and the host they\nare running on. This address family is used by guest agents and hypervisor services that\nneed a communications channel that is independent of virtual machine network configuration.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS** (1 subsections)\n- **DESCRIPTION** (4 subsections)\n- **ERRORS**\n- **VERSIONS**\n- **SEE ALSO**\n- **COLOPHON**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "vsock", "section": "", "mode": "man", "summary": "vsock - Linux VSOCK address family", "synopsis": "", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "bind", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/bind/2/json" }, { "name": "connect", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/connect/2/json" }, { "name": "listen", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/listen/2/json" }, { "name": "recv", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/recv/2/json" }, { "name": "send", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/send/2/json" }, { "name": "socket", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/socket/2/json" }, { "name": "capabilities", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/capabilities/7/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 1, "subsections": [ { "name": "#include ", "lines": 5 } ] }, { "name": "DESCRIPTION", "lines": 22, "subsections": [ { "name": "Address format", "lines": 29 }, { "name": "Live migration", "lines": 7 }, { "name": "Ioctls", "lines": 8 }, { "name": "Local communication", "lines": 6 } ] }, { "name": "ERRORS", "lines": 27, "subsections": [] }, { "name": "VERSIONS", "lines": 7, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "COLOPHON", "lines": 7, "subsections": [] } ], "sections": { "NAME": { "content": "vsock - Linux VSOCK address family\n", "subsections": [] }, "SYNOPSIS": { "content": "", "subsections": [ { "name": "#include ", "content": "#include \n\nstreamsocket = socket(AFVSOCK, SOCKSTREAM, 0);\ndatagramsocket = socket(AFVSOCK, SOCKDGRAM, 0);\n" } ] }, "DESCRIPTION": { "content": "The VSOCK address family facilitates communication between virtual machines and the host they\nare running on. This address family is used by guest agents and hypervisor services that\nneed a communications channel that is independent of virtual machine network configuration.\n\nValid socket types are SOCKSTREAM and SOCKDGRAM. SOCKSTREAM provides connection-oriented\nbyte streams with guaranteed, in-order delivery. SOCKDGRAM provides a connectionless data‐\ngram packet service with best-effort delivery and best-effort ordering. Availability of\nthese socket types is dependent on the underlying hypervisor.\n\nA new socket is created with\n\nsocket(AFVSOCK, sockettype, 0);\n\nWhen a process wants to establish a connection, it calls connect(2) with a given destination\nsocket address. The socket is automatically bound to a free port if unbound.\n\nA process can listen for incoming connections by first binding to a socket address using\nbind(2) and then calling listen(2).\n\nData is transmitted using the send(2) or write(2) families of system calls and data is re‐\nceived using the recv(2) or read(2) families of system calls.\n", "subsections": [ { "name": "Address format", "content": "A socket address is defined as a combination of a 32-bit Context Identifier (CID) and a\n32-bit port number. The CID identifies the source or destination, which is either a virtual\nmachine or the host. The port number differentiates between multiple services running on a\nsingle machine.\n\nstruct sockaddrvm {\nsafamilyt svmfamily; /* Address family: AFVSOCK */\nunsigned short svmreserved1;\nunsigned int svmport; /* Port # in host byte order */\nunsigned int svmcid; /* Address in host byte order */\nunsigned char svmzero[sizeof(struct sockaddr) -\nsizeof(safamilyt) -\nsizeof(unsigned short) -\nsizeof(unsigned int) -\nsizeof(unsigned int)];\n};\n\nsvmfamily is always set to AFVSOCK. svmreserved1 is always set to 0. svmport contains\nthe port number in host byte order. The port numbers below 1024 are called privileged ports.\nOnly a process with the CAPNETBINDSERVICE capability may bind(2) to these port numbers.\nsvmzero must be zero-filled.\n\nThere are several special addresses: VMADDRCIDANY (-1U) means any address for binding;\nVMADDRCIDHYPERVISOR (0) is reserved for services built into the hypervisor; VMADDRCIDLO‐‐\nCAL (1) is the well-known address for local communication (loopback); VMADDRCIDHOST (2) is\nthe well-known address of the host.\n\nThe special constant VMADDRPORTANY (-1U) means any port number for binding.\n" }, { "name": "Live migration", "content": "Sockets are affected by live migration of virtual machines. Connected SOCKSTREAM sockets\nbecome disconnected when the virtual machine migrates to a new host. Applications must re‐\nconnect when this happens.\n\nThe local CID may change across live migration if the old CID is not available on the new\nhost. Bound sockets are automatically updated to the new CID.\n" }, { "name": "Ioctls", "content": "IOCTLVMSOCKETSGETLOCALCID\nGet the CID of the local machine. The argument is a pointer to an unsigned int.\n\nioctl(socket, IOCTLVMSOCKETSGETLOCALCID, &cid);\n\nConsider using VMADDRCIDANY when binding instead of getting the local CID with\nIOCTLVMSOCKETSGETLOCALCID.\n" }, { "name": "Local communication", "content": "VMADDRCIDLOCAL (1) directs packets to the same host that generated them. This is useful\nfor testing applications on a single host and for debugging.\n\nThe local CID obtained with IOCTLVMSOCKETSGETLOCALCID can be used for the same purpose,\nbut it is preferable to use VMADDRCIDLOCAL .\n" } ] }, "ERRORS": { "content": "EACCES Unable to bind to a privileged port without the CAPNETBINDSERVICE capability.\n\nEADDRINUSE\nUnable to bind to a port that is already in use.\n\nEADDRNOTAVAIL\nUnable to find a free port for binding or unable to bind to a nonlocal CID.\n\nEINVAL Invalid parameters. This includes: attempting to bind a socket that is already bound,\nproviding an invalid struct sockaddrvm, and other input validation errors.\n\nENOPROTOOPT\nInvalid socket option in setsockopt(2) or getsockopt(2).\n\nENOTCONN\nUnable to perform operation on an unconnected socket.\n\nEOPNOTSUPP\nOperation not supported. This includes: the MSGOOB flag that is not implemented for\nthe send(2) family of syscalls and MSGPEEK for the recv(2) family of syscalls.\n\nEPROTONOSUPPORT\nInvalid socket protocol number. The protocol should always be 0.\n\nESOCKTNOSUPPORT\nUnsupported socket type in socket(2). Only SOCKSTREAM and SOCKDGRAM are valid.\n", "subsections": [] }, "VERSIONS": { "content": "Support for VMware (VMCI) has been available since Linux 3.9. KVM (virtio) is supported\nsince Linux 4.8. Hyper-V is supported since Linux 4.14.\n\nVMADDRCIDLOCAL is supported since Linux 5.6. Local communication in the guest and on the\nhost is available since Linux 5.6. Previous versions supported only local communication\nwithin a guest (not on the host), and with only some transports (VMCI and virtio).\n", "subsections": [] }, "SEE ALSO": { "content": "bind(2), connect(2), listen(2), recv(2), send(2), socket(2), capabilities(7)\n", "subsections": [] }, "COLOPHON": { "content": "This page is part of release 5.10 of the Linux man-pages project. A description of the\nproject, information about reporting bugs, and the latest version of this page, can be found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nLinux 2020-02-09 VSOCK(7)", "subsections": [] } } } }