Re: [PATCH] vsock.7: document VSOCK socket address family

2018-02-01 Thread Michael Kerrisk (man-pages) 
On 1 February 2018 at 19:03, Stefan Hajnoczi  wrote:
> On Tue, Jan 30, 2018 at 10:31:54PM +0100, Michael Kerrisk (man-pages) wrote:
>> Hi Stefan,
>>
>> Ping on the below please, since it either blocks the man-pages release
>> I'd currently like to make, or I must remove the vsock.7 page for this
>> release.
>
> Sorry for the delay.  The verbatim license is fine.

Thanks, Stefan!

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH] vsock.7: document VSOCK socket address family

2018-02-01 Thread Stefan Hajnoczi 
On Tue, Jan 30, 2018 at 10:31:54PM +0100, Michael Kerrisk (man-pages) wrote:
> Hi Stefan,
> 
> Ping on the below please, since it either blocks the man-pages release
> I'd currently like to make, or I must remove the vsock.7 page for this
> release.

Sorry for the delay.  The verbatim license is fine.

Stefan


signature.asc
Description: PGP signature

Re: [PATCH] vsock.7: document VSOCK socket address family

2018-01-30 Thread Michael Kerrisk (man-pages) 
Hi Stefan,

Ping on the below please, since it either blocks the man-pages release
I'd currently like to make, or I must remove the vsock.7 page for this
release.

Thanks,

Michael



On 26 January 2018 at 22:47, Michael Kerrisk (man-pages)
 wrote:
> Stefan,
>
> I've just now noted that your page came with no license. What license
> do you want to use Please see
> https://www.kernel.org/doc/man-pages/licenses.html
>
> Thanks,
>
> Michael
>
>
> On 30 November 2017 at 12:21, Stefan Hajnoczi  wrote:
>> The AF_VSOCK address family has been available since Linux 3.9 without a
>> corresponding man page.
>>
>> This patch adds vsock.7 and describes its use along the same lines as
>> existing ip.7, unix.7, and netlink.7 man pages.
>>
>> CC: Jorgen Hansen 
>> CC: Dexuan Cui 
>> Signed-off-by: Stefan Hajnoczi 
>> ---
>>  man7/vsock.7 | 175 
>> +++
>>  1 file changed, 175 insertions(+)
>>  create mode 100644 man7/vsock.7
>>
>> diff --git a/man7/vsock.7 b/man7/vsock.7
>> new file mode 100644
>> index 0..48c6c2e1e
>> --- /dev/null
>> +++ b/man7/vsock.7
>> @@ -0,0 +1,175 @@
>> +.TH VSOCK 7 2017-11-30 "Linux" "Linux Programmer's Manual"
>> +.SH NAME
>> +vsock \- Linux VSOCK address family
>> +.SH SYNOPSIS
>> +.B #include 
>> +.br
>> +.B #include 
>> +.PP
>> +.IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);"
>> +.br
>> +.IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);"
>> +.SH DESCRIPTION
>> +The VSOCK address family facilitates communication between virtual machines 
>> and
>> +the host they are running on.  This address family is used by guest agents 
>> and
>> +hypervisor services that need a communications channel that is independent 
>> of
>> +virtual machine network configuration.
>> +.PP
>> +Valid socket types are
>> +.B SOCK_STREAM
>> +and
>> +.B SOCK_DGRAM .
>> +.B SOCK_STREAM
>> +provides connection-oriented byte streams with guaranteed, in-order 
>> delivery.
>> +.B SOCK_DGRAM
>> +provides a connectionless datagram packet service.  Availability of these
>> +socket types is dependent on the underlying hypervisor.
>> +.PP
>> +A new socket is created with
>> +.PP
>> +socket(AF_VSOCK, socket_type, 0);
>> +.PP
>> +When a process wants to establish a connection it calls
>> +.BR connect (2)
>> +with a given destination socket address.  The socket is automatically bound 
>> to
>> +a free port if unbound.
>> +.PP
>> +A process can listen for incoming connections by first binding to a socket 
>> address using
>> +.BR bind (2)
>> +and then calling
>> +.BR listen (2).
>> +.PP
>> +Data is transferred using the usual
>> +.BR send (2)
>> +and
>> +.BR recv (2)
>> +family of socket system calls.
>> +.SS Address format
>> +A socket address is defined as a combination of a 32-bit Context Identifier 
>> (CID) and a 32-bit port number.  The CID identifies the source or 
>> destination, which is either a virtual machine or the host.  The port number 
>> differentiates between multiple services running on a single machine.
>> +.PP
>> +.in +4n
>> +.EX
>> +struct sockaddr_vm {
>> +sa_family_t svm_family; /* address family: AF_VSOCK */
>> +unsigned short  svm_reserved1;
>> +unsigned intsvm_port;   /* port in native byte order */
>> +unsigned intsvm_cid;/* address in native byte order */
>> +};
>> +.EE
>> +.in
>> +.PP
>> +.I svm_family
>> +is always set to
>> +.BR AF_VSOCK .
>> +.I svm_reserved1
>> +is always set to 0.
>> +.I svm_port
>> +contains the port in native byte order.
>> +The port numbers below 1024 are called
>> +.IR "privileged ports" .
>> +Only a process with
>> +.B CAP_NET_BIND_SERVER
>> +capability may
>> +.BR bind (2)
>> +to these port numbers.
>> +.PP
>> +There are several special addresses:
>> +.B VMADDR_CID_ANY
>> +(-1U)
>> +means any address for binding;
>> +.B VMADDR_CID_HYPERVISOR
>> +(0) and
>> +.B VMADDR_CID_RESERVED
>> +(1) are unused addresses;
>> +.B VMADDR_CID_HOST
>> +(2)
>> +is the well-known address of the host.
>> +.PP
>> +The special constant
>> +.B VMADDR_PORT_ANY
>> +(-1U)
>> +means any port number for binding.
>> +.SS Live migration
>> +Sockets are affected by live migration of virtual machines.  Connected
>> +.B SOCK_STREAM
>> +sockets become disconnected when the virtual machine migrates to a new host.
>> +Applications must reconnect when this happens.
>> +.PP
>> +The local CID may change across live migration if the old CID is not 
>> available
>> +on the new host.  Bound sockets are automatically updated to the new CID.
>> +.SS Ioctls
>> +.TP
>> +.B IOCTL_VM_SOCKETS_GET_LOCAL_CID
>> +Get the CID of the local machine.  The argument is a pointer to an unsigned 
>> int.
>> +.IP
>> +.in +4n
>> +.EX
>> +.IB error " = ioctl(" socket ", " IOCTL_VM_SOCKETS_GET_LOCAL_CID ", "  
>> ");"
>> +.EE
>> +.in
>> +.IP
>> +Consider using
>> +.B VMADDR_CID_ANY
>> +when binding instead of

Re: [PATCH] vsock.7: document VSOCK socket address family

2018-01-26 Thread Michael Kerrisk (man-pages) 
Stefan,

I've just now noted that your page came with no license. What license
do you want to use Please see
https://www.kernel.org/doc/man-pages/licenses.html

Thanks,

Michael


On 30 November 2017 at 12:21, Stefan Hajnoczi  wrote:
> The AF_VSOCK address family has been available since Linux 3.9 without a
> corresponding man page.
>
> This patch adds vsock.7 and describes its use along the same lines as
> existing ip.7, unix.7, and netlink.7 man pages.
>
> CC: Jorgen Hansen 
> CC: Dexuan Cui 
> Signed-off-by: Stefan Hajnoczi 
> ---
>  man7/vsock.7 | 175 
> +++
>  1 file changed, 175 insertions(+)
>  create mode 100644 man7/vsock.7
>
> diff --git a/man7/vsock.7 b/man7/vsock.7
> new file mode 100644
> index 0..48c6c2e1e
> --- /dev/null
> +++ b/man7/vsock.7
> @@ -0,0 +1,175 @@
> +.TH VSOCK 7 2017-11-30 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +vsock \- Linux VSOCK address family
> +.SH SYNOPSIS
> +.B #include 
> +.br
> +.B #include 
> +.PP
> +.IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);"
> +.br
> +.IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);"
> +.SH DESCRIPTION
> +The VSOCK address family facilitates communication between virtual machines 
> and
> +the host they are running on.  This address family is used by guest agents 
> and
> +hypervisor services that need a communications channel that is independent of
> +virtual machine network configuration.
> +.PP
> +Valid socket types are
> +.B SOCK_STREAM
> +and
> +.B SOCK_DGRAM .
> +.B SOCK_STREAM
> +provides connection-oriented byte streams with guaranteed, in-order delivery.
> +.B SOCK_DGRAM
> +provides a connectionless datagram packet service.  Availability of these
> +socket types is dependent on the underlying hypervisor.
> +.PP
> +A new socket is created with
> +.PP
> +socket(AF_VSOCK, socket_type, 0);
> +.PP
> +When a process wants to establish a connection it calls
> +.BR connect (2)
> +with a given destination socket address.  The socket is automatically bound 
> to
> +a free port if unbound.
> +.PP
> +A process can listen for incoming connections by first binding to a socket 
> address using
> +.BR bind (2)
> +and then calling
> +.BR listen (2).
> +.PP
> +Data is transferred using the usual
> +.BR send (2)
> +and
> +.BR recv (2)
> +family of socket system calls.
> +.SS Address format
> +A socket address is defined as a combination of a 32-bit Context Identifier 
> (CID) and a 32-bit port number.  The CID identifies the source or 
> destination, which is either a virtual machine or the host.  The port number 
> differentiates between multiple services running on a single machine.
> +.PP
> +.in +4n
> +.EX
> +struct sockaddr_vm {
> +sa_family_t svm_family; /* address family: AF_VSOCK */
> +unsigned short  svm_reserved1;
> +unsigned intsvm_port;   /* port in native byte order */
> +unsigned intsvm_cid;/* address in native byte order */
> +};
> +.EE
> +.in
> +.PP
> +.I svm_family
> +is always set to
> +.BR AF_VSOCK .
> +.I svm_reserved1
> +is always set to 0.
> +.I svm_port
> +contains the port in native byte order.
> +The port numbers below 1024 are called
> +.IR "privileged ports" .
> +Only a process with
> +.B CAP_NET_BIND_SERVER
> +capability may
> +.BR bind (2)
> +to these port numbers.
> +.PP
> +There are several special addresses:
> +.B VMADDR_CID_ANY
> +(-1U)
> +means any address for binding;
> +.B VMADDR_CID_HYPERVISOR
> +(0) and
> +.B VMADDR_CID_RESERVED
> +(1) are unused addresses;
> +.B VMADDR_CID_HOST
> +(2)
> +is the well-known address of the host.
> +.PP
> +The special constant
> +.B VMADDR_PORT_ANY
> +(-1U)
> +means any port number for binding.
> +.SS Live migration
> +Sockets are affected by live migration of virtual machines.  Connected
> +.B SOCK_STREAM
> +sockets become disconnected when the virtual machine migrates to a new host.
> +Applications must reconnect when this happens.
> +.PP
> +The local CID may change across live migration if the old CID is not 
> available
> +on the new host.  Bound sockets are automatically updated to the new CID.
> +.SS Ioctls
> +.TP
> +.B IOCTL_VM_SOCKETS_GET_LOCAL_CID
> +Get the CID of the local machine.  The argument is a pointer to an unsigned 
> int.
> +.IP
> +.in +4n
> +.EX
> +.IB error " = ioctl(" socket ", " IOCTL_VM_SOCKETS_GET_LOCAL_CID ", "  
> ");"
> +.EE
> +.in
> +.IP
> +Consider using
> +.B VMADDR_CID_ANY
> +when binding instead of getting the local CID with
> +.B IOCTL_VM_SOCKETS_GET_LOCAL_CID .
> +.SH ERRORS
> +.TP
> +.B EACCES
> +Unable to bind to a privileged port without the
> +.B CAP_NET_BIND_SERVICE
> +capability.
> +.TP
> +.B EINVAL
> +Invalid parameters.  This includes:
> +attempting to bind a socket that is already bound, providing an invalid 
> struct
> +.B sockaddr_vm ,
> +and other input validation errors.
> +.TP
> +.B EOPNOTSUPP
> +Operation not

Re: [PATCH] vsock.7: document VSOCK socket address family

2017-12-02 Thread Stefan Hajnoczi 
On Fri, Dec 01, 2017 at 09:57:04AM -0500, G. Branden Robinson wrote:
> At 2017-12-01T13:09:01+, Stefan Hajnoczi wrote:
> > On Thu, Nov 30, 2017 at 01:21:26PM +, Jorgen S. Hansen wrote:
> > > > On Nov 30, 2017, at 12:21 PM, Stefan Hajnoczi  
> > > > wrote:
> > 
> > Thanks for the quick review!
> > 
> > I forgot to ask you: Is SOCK_DGRAM reliable and in-order over VMCI?
> > 
> > > > +.PP
> > > > +Valid socket types are
> > > > +.B SOCK_STREAM
> > > > +and
> > > > +.B SOCK_DGRAM .
> > > 
> > > The space here results in a space between SOCK_DGRAM and the “.” in the 
> > > formatted text. Is that intentional?
> > 
> > I haven't figured out the groff syntax to avoid the space :(.  Any
> > ideas?
> 
> What you want is the .BR macro.
> 
> .BR SOCK_DGRAM .
> 
> The man macro package defines six "two-font" macros for switching
> between roman, bold, and italic faces without intervening space.
> 
> See man(7) and groff_man(7).

Excellent, thank you!

Stefan


signature.asc
Description: PGP signature

Re: [PATCH] vsock.7: document VSOCK socket address family

2017-12-01 Thread G. Branden Robinson 
At 2017-12-01T13:09:01+, Stefan Hajnoczi wrote:
> On Thu, Nov 30, 2017 at 01:21:26PM +, Jorgen S. Hansen wrote:
> > > On Nov 30, 2017, at 12:21 PM, Stefan Hajnoczi  wrote:
> 
> Thanks for the quick review!
> 
> I forgot to ask you: Is SOCK_DGRAM reliable and in-order over VMCI?
> 
> > > +.PP
> > > +Valid socket types are
> > > +.B SOCK_STREAM
> > > +and
> > > +.B SOCK_DGRAM .
> > 
> > The space here results in a space between SOCK_DGRAM and the “.” in the 
> > formatted text. Is that intentional?
> 
> I haven't figured out the groff syntax to avoid the space :(.  Any
> ideas?

What you want is the .BR macro.

.BR SOCK_DGRAM .

The man macro package defines six "two-font" macros for switching
between roman, bold, and italic faces without intervening space.

See man(7) and groff_man(7).

-- 
Regards,
Branden


signature.asc
Description: PGP signature

Re: [PATCH] vsock.7: document VSOCK socket address family

2017-12-01 Thread Jorgen S. Hansen 

> On Dec 1, 2017, at 2:09 PM, Stefan Hajnoczi  wrote:
> 
> On Thu, Nov 30, 2017 at 01:21:26PM +, Jorgen S. Hansen wrote:
>>> On Nov 30, 2017, at 12:21 PM, Stefan Hajnoczi  wrote:
> 
> Thanks for the quick review!
> 
> I forgot to ask you: Is SOCK_DGRAM reliable and in-order over VMCI?

No, that isn’t guaranteed.

> 
>>> +.PP
>>> +Valid socket types are
>>> +.B SOCK_STREAM
>>> +and
>>> +.B SOCK_DGRAM .
>> 
>> The space here results in a space between SOCK_DGRAM and the “.” in the 
>> formatted text. Is that intentional?
> 
> I haven't figured out the groff syntax to avoid the space :(.  Any
> ideas?

Looks like man 7 unix has a few examples with bold and “,” - maybe look at the 
source for that.

> 
>> Apart from the nits, this looks great.
> 
> Please let me know if there are any other topics that we should cover in
> the man page.

Sure, I’ll get back to you soon, if I think of anything.

Thanks,
Jorgen

Re: [PATCH] vsock.7: document VSOCK socket address family

2017-12-01 Thread Stefan Hajnoczi 
On Thu, Nov 30, 2017 at 01:21:26PM +, Jorgen S. Hansen wrote:
> > On Nov 30, 2017, at 12:21 PM, Stefan Hajnoczi  wrote:

Thanks for the quick review!

I forgot to ask you: Is SOCK_DGRAM reliable and in-order over VMCI?

> > +.PP
> > +Valid socket types are
> > +.B SOCK_STREAM
> > +and
> > +.B SOCK_DGRAM .
> 
> The space here results in a space between SOCK_DGRAM and the “.” in the 
> formatted text. Is that intentional?

I haven't figured out the groff syntax to avoid the space :(.  Any
ideas?

> > +.PP
> > +There are several special addresses:
> > +.B VMADDR_CID_ANY
> > +(-1U)
> > +means any address for binding;
> > +.B VMADDR_CID_HYPERVISOR
> 
> We use VMADDR_CID_HYPERVISOR for communicating with services in the 
> hypervisor, so you could describe this as “an address reserved for services 
> built into the hypervisor”.

Will fix.

> > +.SH VERSIONS
> > +Support for VMware has been available since Linux 3.9.  KVM (virtio) is
> 
> VMware (VMCI) for clarity.

Will fix.

> Apart from the nits, this looks great.

Please let me know if there are any other topics that we should cover in
the man page.


signature.asc
Description: PGP signature

Re: [PATCH] vsock.7: document VSOCK socket address family

2017-11-30 Thread Jorgen S. Hansen 

> On Nov 30, 2017, at 12:21 PM, Stefan Hajnoczi  wrote:
> 
> The AF_VSOCK address family has been available since Linux 3.9 without a
> corresponding man page.
> 
> This patch adds vsock.7 and describes its use along the same lines as
> existing ip.7, unix.7, and netlink.7 man pages.
> 
> CC: Jorgen Hansen 
> CC: Dexuan Cui 
> Signed-off-by: Stefan Hajnoczi 
> ---
> man7/vsock.7 | 175 +++
> 1 file changed, 175 insertions(+)
> create mode 100644 man7/vsock.7
> 
> diff --git a/man7/vsock.7 b/man7/vsock.7
> new file mode 100644
> index 0..48c6c2e1e
> --- /dev/null
> +++ b/man7/vsock.7
> @@ -0,0 +1,175 @@
> +.TH VSOCK 7 2017-11-30 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +vsock \- Linux VSOCK address family
> +.SH SYNOPSIS
> +.B #include 
> +.br
> +.B #include 
> +.PP
> +.IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);"
> +.br
> +.IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);"
> +.SH DESCRIPTION
> +The VSOCK address family facilitates communication between virtual machines 
> and
> +the host they are running on.  This address family is used by guest agents 
> and
> +hypervisor services that need a communications channel that is independent of
> +virtual machine network configuration.
> +.PP
> +Valid socket types are
> +.B SOCK_STREAM
> +and
> +.B SOCK_DGRAM .

The space here results in a space between SOCK_DGRAM and the “.” in the 
formatted text. Is that intentional?

> +.B SOCK_STREAM
> +provides connection-oriented byte streams with guaranteed, in-order delivery.
> +.B SOCK_DGRAM
> +provides a connectionless datagram packet service.  Availability of these
> +socket types is dependent on the underlying hypervisor.
> +.PP
> +A new socket is created with
> +.PP
> +socket(AF_VSOCK, socket_type, 0);
> +.PP
> +When a process wants to establish a connection it calls
> +.BR connect (2)
> +with a given destination socket address.  The socket is automatically bound 
> to
> +a free port if unbound.
> +.PP
> +A process can listen for incoming connections by first binding to a socket 
> address using
> +.BR bind (2)
> +and then calling
> +.BR listen (2).
> +.PP
> +Data is transferred using the usual
> +.BR send (2)
> +and
> +.BR recv (2)
> +family of socket system calls.
> +.SS Address format
> +A socket address is defined as a combination of a 32-bit Context Identifier 
> (CID) and a 32-bit port number.  The CID identifies the source or 
> destination, which is either a virtual machine or the host.  The port number 
> differentiates between multiple services running on a single machine.
> +.PP
> +.in +4n
> +.EX
> +struct sockaddr_vm {
> +sa_family_t svm_family; /* address family: AF_VSOCK */
> +unsigned short  svm_reserved1;
> +unsigned intsvm_port;   /* port in native byte order */
> +unsigned intsvm_cid;/* address in native byte order */
> +};
> +.EE
> +.in
> +.PP
> +.I svm_family
> +is always set to
> +.BR AF_VSOCK .

Again the space before “."

> +.I svm_reserved1
> +is always set to 0.
> +.I svm_port
> +contains the port in native byte order.
> +The port numbers below 1024 are called
> +.IR "privileged ports" .
> +Only a process with
> +.B CAP_NET_BIND_SERVER
> +capability may
> +.BR bind (2)
> +to these port numbers.
> +.PP
> +There are several special addresses:
> +.B VMADDR_CID_ANY
> +(-1U)
> +means any address for binding;
> +.B VMADDR_CID_HYPERVISOR

We use VMADDR_CID_HYPERVISOR for communicating with services in the hypervisor, 
so you could describe this as “an address reserved for services built into the 
hypervisor”.

> +(0) and
> +.B VMADDR_CID_RESERVED
> +(1) are unused addresses;
> +.B VMADDR_CID_HOST
> +(2)
> +is the well-known address of the host.
> +.PP
> +The special constant
> +.B VMADDR_PORT_ANY
> +(-1U)
> +means any port number for binding.
> +.SS Live migration
> +Sockets are affected by live migration of virtual machines.  Connected
> +.B SOCK_STREAM
> +sockets become disconnected when the virtual machine migrates to a new host.
> +Applications must reconnect when this happens.
> +.PP
> +The local CID may change across live migration if the old CID is not 
> available
> +on the new host.  Bound sockets are automatically updated to the new CID.
> +.SS Ioctls
> +.TP
> +.B IOCTL_VM_SOCKETS_GET_LOCAL_CID
> +Get the CID of the local machine.  The argument is a pointer to an unsigned 
> int.
> +.IP
> +.in +4n
> +.EX
> +.IB error " = ioctl(" socket ", " IOCTL_VM_SOCKETS_GET_LOCAL_CID ", "  
> ");"
> +.EE
> +.in
> +.IP
> +Consider using
> +.B VMADDR_CID_ANY
> +when binding instead of getting the local CID with
> +.B IOCTL_VM_SOCKETS_GET_LOCAL_CID .

space before “.”

> +.SH ERRORS
> +.TP
> +.B EACCES
> +Unable to bind to a privileged port without the
> +.B CAP_NET_BIND_SERVICE
> +capability.
> +.TP
> +.B EINVAL
> +Invalid parameters.  This includes:
> +attempting to bind a socket