blob: b91d27b64ef277d1715a6fa771f5f837243bf119 [file] [log] [blame]
Internet Engineering Task Force G. D'Amore, Ed.
Internet-Draft
Intended status: Informational M. Sustrik
Expires: October 14, 2016
April 12, 2016
IPC Mapping for Scalability Protocols
sp-ipc-mapping-01
Abstract
This document defines the IPC mapping for scalability protocols. It
deals with how IPC (inter-process communication) should be
implemented on POSIX-compliant platforms.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 14, 2016.
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
D'Amore & Sustrik Expires October 14, 2016 [Page 1]
Internet-Draft IPC mapping for SPs April 2016
1. Underlying protocol
This mapping should be layered directly on the top of AF_UNIX sockets
of type SOCK_STREAM. On the platforms where AF_UNIX sockets are not
available IPC mapping may be done in a platform-specific way and
SHOULD be described in a separate RFC.
There's no fixed file to use for SP communication. Instead,
filenames are assigned to individual services by the user.
2. Connection initiation
Before binding the AF_UNIX socket the implementation SHOULD check
whether there's another process bound to the address. If not so it
SHOULD try to delete the associated file, if present. This measure
will prevent subsequent bind from failing if there's a leftover file
from the previous runs of the application.
The check can be performed in a platform-specific way, however, a
generic way to implement it is to try to connect to the address and
close the connection immediately if successful.
After establishing underlying AF_UNIX connection, both parties MUST
send the protocol header immediately. Both endpoints MUST then wait
for the protocol header from the peer before proceeding on.
The protocol header is 8 bytes long and looks like this:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x00 | 0x53 | 0x50 | version |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| type | reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
First four bytes of the protocol header are used to make sure that
the peer's protocol is compatible with the protocol used by the local
endpoint.
First four bytes of the protocol header MUST be set to 0x00, 0x53,
0x50 and 0x00 respectively. If the protocol header received from the
peer differs, the TCP connection MUST be closed immediately.
The fact that the first byte of the protocol header is binary zero
eliminates any text-based protocols that were accidentally connected
to the endpoint. Subsequent two bytes make the check even more
rigorous. At the same time they can be used as a debugging hint to
D'Amore & Sustrik Expires October 14, 2016 [Page 2]
Internet-Draft IPC mapping for SPs April 2016
indicate that the connection is supposed to use one of the
scalability protocols -- ASCII representation of these bytes is 'SP'.
Finally, the fourth byte rules out any incompatible versions of this
protocol.
Fifth and sixth bytes of the header form a 16-bit unsigned integer in
network byte order representing the type of SP endpoint on the layer
above. The value SHOULD NOT be interpreted by the mapping, rather
the interpretation should be delegated to the scalability protocol
above the mapping. For informational purposes, it should be noted
that the field encodes information such as SP protocol ID, protocol
version and the role of endpoint within the protocol. Individual
values are assigned by IANA.
Finally, the last two bytes of the protocol header are reserved for
future use and must be set to binary zeroes. If the protocol header
from the peer contains anything else than zeroes in this field, the
implementation MUST close the underlying TCP connection.
3. Message header
Once the protocol header is accepted, endpoint can send and receive
messages. Every message starts with a message header consisting of
of a single byte called 'message type'.
The only value of this field that is currently allowed is 0x1, which
means "in-band" message, i.e. message whose body is passed as a
stream of bytes via the AF_UNIX socket.
The intent of this field is to eventually allow out-of-band transfer
of the message bodies, e.g. via shared memory.
The in-band message type MUST be implemented.
4. In-band messages
For in-band messages, message header is immediately followed by
64-bit unsigned integer in network byte order representing the
payload size, in bytes. Thus, the message payload can be from 0 to
2^64-1 bytes long. The payload of the specified size follows
directly after the size field:
+-----------+------------+-----------------+
| type (8b) | size (64b) | payload |
+-----------+------------+-----------------+
D'Amore & Sustrik Expires October 14, 2016 [Page 3]
Internet-Draft IPC mapping for SPs April 2016
5. IANA Considerations
This memo includes no request to IANA.
6. Security Considerations
The mapping isn't intended to provide any additional security in
addition to what AF_UNIX does.
Authors' Addresses
Garrett D'Amore (editor)
Email: garrett@damore.org
Martin Sustrik
Email: sustrik@250bpm.com
D'Amore & Sustrik Expires October 14, 2016 [Page 4]