Network Working Group F. Risso Internet-Draft Politecnico di Torino Expires: August 25, 2003 D. Dutt Cisco Systems February 24, 2003 REmote Sample and CApture Protocol (RESCAP) draft-risso-rescap-00 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. 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." The list of current Internet-Drafts can be accessed at http:// www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on August 25, 2003. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract This document details a configuration protocol that can be used to capture and sample frames on a remote device. This protocol defines a control connection, which is used to control the remote device, and a data connection, which is used to transport back the sampled data. This protocol includes has a set of optional parameters (e.g. custom filters, etc) that allows customizing the behavior of the sampling process. This protocol can be used also for packet capture and it should be possible to implement it on both network devices (router and switches) and workstation hosts. Risso & Dutt Expires August 25, 2003 [Page 1] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Existing Solutions . . . . . . . . . . . . . . . . . . . . . 3 1.2 Features Overview . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . 7 3.1 Network Protocols in Use . . . . . . . . . . . . . . . . . . 7 4. Remote Sample and Capture Protocol (RESCAP) . . . . . . . . 9 4.1 Connection Setup . . . . . . . . . . . . . . . . . . . . . . 9 4.2 General Header Message Format . . . . . . . . . . . . . . . 9 4.3 Control Protocol Messages . . . . . . . . . . . . . . . . . 10 4.4 RESCAP Timers . . . . . . . . . . . . . . . . . . . . . . . 11 4.5 Security . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5. RESCAP Messages . . . . . . . . . . . . . . . . . . . . . . 13 5.1 Authorization Message (Message Type = AUTH) . . . . . . . . 13 5.2 Find All Interfaces Message (Message Type = FIND_ALL_INT) . 13 5.3 Open RESCAP Session (Message Type = OPEN_SESSION) . . . . . 15 5.4 Close Session (Message Type = CLOSE_SESSION) . . . . . . . . 16 5.5 Close RESCAP Connection (Message Type = CLOSE) . . . . . . . 17 5.6 Start Sampling (Message Type = START_SAMPLING) . . . . . . . 17 5.6.1 Filtering Section . . . . . . . . . . . . . . . . . . . . . 20 5.6.2 Sampling Information Section . . . . . . . . . . . . . . . . 20 5.6.3 Data Connection Information Section . . . . . . . . . . . . 20 5.7 End Sampling (Message Type = END_SAMPLING) . . . . . . . . . 20 5.8 Adjust Sampling Parameters (Message Type = ADJUST_SAMPLING_PARS) . . . . . . . . . . . . . . . . . . . 21 5.9 Get Sampling Statistics (Message Type = GET_SAMPLING_STATS) . . . . . . . . . . . . . . . . . . . . 21 5.10 Error Message (Message Type = ERROR) . . . . . . . . . . . . 23 6. RESCAP Codes and Values . . . . . . . . . . . . . . . . . . 24 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 25 Intellectual Property and Copyright Statements . . . . . . . 26 Risso & Dutt Expires August 25, 2003 [Page 2] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 1. Introduction There are many devices (routers, switches, workstations) on which it would be useful to sample or capture incoming and outgoing traffic to debug problems. These devices could not support graphical analyzers that can do detailed and sophisticated analysis in place. The Remote Sample and CApture Protocol (RESCAP) is an attempt to circumvent this problem by capturing the local traffic and sending it to a remote destination where a tool such as a graphical protocol analyzer can capture, monitor and analyze the traffic. Due to the avaiability of high quality public domain tools for packet capture, the RESCAP protocol wants to address the needs of packet sampling on both network equipment and workstation hosts. For instance, workstations can be easily updated to support the new protocol, while network devices could experiment more problems in the early adoption phase. Hence, the support of RESCAP on standard *nix and Win32 workstation is one of the goals of this proposal. However, this could lead to some duplication of data because some information that can be retrieved by means of SNMP and RMON protocols are not avaiable when the sampling device is a standard workstation host. Therefore, RESCAP will define also some basic operations (like listing the interfaces, etc.) that are not avaiable by other ways on these devices. Since the Packet Capture can be seen as a special case of Packet Sampling, the terms "sample" and "sampling" (instead of "capture") will be used throughout this draft. 1.1 Existing Solutions On standard switches and routers, today a protocol analyzer must be connected to a switch port directly in order to debug packets being handled by the device; this of course requires that a port on the switch be dedicated. Using remote capture, the traffic can be switched to laptops not even on the local network. This is very useful for support engineers in debugging devices in the field. Additionally, remote software offers greater flexibility than on-device tools, since it can be easily updated and it can take advantage of higher processing capabilities. The network device can become a probe with limited processing capability, while most of the intelligence rely on the remote monitoring station. While some proprietary solutions exist for packet capture, nothing exist for packet sampling. This task is getting increasing importance since packet sampling is often the only way to know (and to predict) Risso & Dutt Expires August 25, 2003 [Page 3] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 the status of the network, and this data can be used for traffic engineering and more. This proposal aims at defining a standard solution for remote packet sample (and capture) over remote devices. 1.2 Features Overview The main features of RESCAP are: o Support for sampling from a specific interface of the remote device o Support for specifying filters remotely to avoid unnecessary packets from being sent to the sampling device o Support for capturing all the packets on the remote interface o Support for active and passive modes to support sampling across firewalls o Support for heterogeneous devices such as hosts (*nix, Windows), routers and switches Risso & Dutt Expires August 25, 2003 [Page 4] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 2. Terminology Sampling Process The sampling process extracts a subset (according to some configuration parameters) of the network packets and it sends them to one collecting process. Sampling Device (or Probe) The probe is the physical device that runs one or more sampling processes. Collecting Process The collecting process receives sampled packets from one or more sampling processes. The collecting process might store received flow records or further process them, but these actions are out of the scope of this document. Collecting Device The collecting device is a physical device that runs one or more collecting processes. Active Mode The active mode is a running mode in which the sampling process initiates the control connection (i.e. it becomes an "active" device) towards the collecting process. This is useful to overcome the problem of a probe behind firewalls (or network address translators) while the collecting process is on the public Internet. Passive Mode The passive mode is the standard running mode in which the collecting process initiates the control connection towards the sampling process. In this case the sampling process waits for new control connections, i.e. it looks like a "passive" device. Control Connection A transport-layer reliable connection (TCP) between a collecting device and a sampling device, which is used to control the sampling process and to get some control statistics (e.g. the number of sampled and dropped packets so far). Data Connection A transport-layer connection between a collecting process and the corresponding sampling process, which is used to exchange data (sampled frames). This connection can use either TCP or UDP (in this case it does not guarantee any kind of reliability). Risso & Dutt Expires August 25, 2003 [Page 5] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 Sampling Session A logical association between one sampling process (on the sampling device) and one collecting process (on the collecting device), which exchange information by means of a control connection and a data connection. Risso & Dutt Expires August 25, 2003 [Page 6] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 3. Protocol Overview The Remote Sampling and CApture Protocol (RESCAP) is structured as a client-server protocol on top of TCP/ UDP. The protocol consists of two connections, one for control (control connection) and the other for actually transferring the sampled frames (data connection). The former uses TCP and the latter can use either TCP or UDP. The protocol messages use a TLV-like format to communicate objects. The sampled frames are preceded by an header with some statistical information. On the probe, a daemon accepts (or initiates in case of Active Mode) control connections from a collecting process on the collecting device and it creates the appropriate sampling process. The sampling process and the collecting process exchange ther information through the control and data connections. While there can be only one control connection between one collecting and sampling device, there can be more than one data connection since this is intented as a comminication channel between collecting and sampling processes. For instance, multiple sampling processes can simultaneously sample traffic on the same interface of a remote device. In addition, username/password can be required to authenticate the commincation between collecting and sampling devices. 3.1 Network Protocols in Use The RESCAP protocol makes use of two types of connections: the Control Connection, which is used to trasport commands and responses between two entities, and the Data Connection, which is devoted to transport data. While the former is made up of a TCP connection, the latter can be either TCP or UDP at user's choice. However, the UDP protocol has severe impacts in network performance and it is strongly discouraged. However, there are some cases in which a UDP connection can be appropriate. For instance, the UDP inserts a litte overhead on packet transmission and it is provided because of some limited cases in which the TCP is not appropriate: o high volume (and speed) sampling: it can be useful to perform high volume of packet sampling over high speed (e.g. gigabit) links, because the overhead due to TCP processing can be too high to sustain. o local area network sampling: it can be useful when sampling and collecting devices are connected by means of a direct cable (e.g. when the sampling is performed on a locally attached switch); a Risso & Dutt Expires August 25, 2003 [Page 7] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 congestion control mechanism is useless in such these cases. Risso & Dutt Expires August 25, 2003 [Page 8] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 4. Remote Sample and Capture Protocol (RESCAP) This section details the remote sample and capture protocol itself. 4.1 Connection Setup Remote sampling is started by first establishing the control connection between the sampling device and the collecting device. The connection maybe initiated either by the sampling device (passive mode) or the collecting device (active mode). The port associated with this connection is assumed to be well-known. If it is required to sample traffic from a device behind a firewall, there are two solutions possible: one is to configure the firewall to allow RESCAP to pass through or support a mode whereby the sampling device will initiate the control connection thereby piercing through the firewall. RESCAP supports both solutions. In order to support the functionality of allowing the sampling device to initiate the connection to the collecting device, it is assumed that the collecting process is running and it is ready to accept connections from the sampling device. The actual traffic that is sampled is sent on a separate connection (data connection) established between the two devices. This can be a TCP connection or can use UDP. Similar to the control connection, this connection maybe setup by either end based on the configuration. 4.2 General Header Message Format The message format consists of a general header optionally followed by a command-specific header. The format of the general header is shown in Figure 1. o Version: denotes the version of the message, set to 1 currently. o Response: if it is set, it is a response message. o Type: message type such as OPEN_SESSION, START_SAMPLING, etc. The topmost bit (R) indicates whether this is a request or a response. o Value: it has a message-dependent meaning and it is used to carry short values that can be encoded in 16 bits (such as number of interfaces). o Length: length of the rest of this message. Risso & Dutt Expires August 25, 2003 [Page 9] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 0 7 8 15 31 +-------------+-+-----------+---------------------------+ | Version |R| Msg Type | Value | +-------------+-+-----------+---------------------------+ | Payload Length | +-------------------------------------------------------+ / Variable Length Payload / +-------------------------------------------------------+ Figure 1: General Header Message Format 4.3 Control Protocol Messages The currently defined protocol messages are: o AUTH: it transports an authorization message. o FIND_ALL_INT: it obtains the list of interfaces available on the sampling device. o OPEN_SESSION: it creates a new session between one sampling process and one collecting process. o CLOSE_SESSION: it closes an existing session between one sampling process and one collecting process. o CLOSE: it closes an existing control connection between one sampling device and one collecting device. o START_SAMPLING: it begins sampling packets within an existing session. o END_SAMPLING: it ends sampling packets within an existing session. o ADJUST_SAMPLING_PARS: it adjusts the parameters of the current sampling session. o GET_SAMPLING_STATS: it gets some statistical information about the current sampling session. o ERROR: it reports back the information related to an error occurred to the other end process. All the previous messages (with the exception of ERROR) esist in both the Request and Reply forms, since the sampling and collecting processes must notify the result of the issued command. In case the Request message fails, the Reply message is missing and an ERROR Risso & Dutt Expires August 25, 2003 [Page 10] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 message is returned back instead. For instance, the ERROR message is the only message which is not available in the Request and Reply forms. Sometimes, a message does not have any payload (e.g. if the authentication phase completed succesfully, the reply message is just "OK"). In this case the message will have only the General Header with the appropriate value into the Message Type field, while the Payload Length will be zero. 4.4 RESCAP Timers There are two kinds of timers that are used in RESCAP. Both are on the server side: o INIT_TIMEOUT: this timer is used to decide the duration to wait for an AUTH message. If an AUTH message is not received within this time, the connection is terminated. o RUN_TIMEOUT: this timer is used after authentication and when a sampling session is not active. It specifies the duration to wait for a message to arrive from the client after successful authentication; if no message arrives within this duration, the connection is terminated. This timer is not used in the active mode because the control connection must last forever (until the collecting device explicitely kills it). 4.5 Security There are two main issues related to security: o Authentication of host and/or user attempting the remote sampling. o Encrypting the control or sampled traffic to prevent third-party snooping. Authentication of the host is enabled by configuring the remote sampling daemon to accept (or initiate) connections to a specified set of IP addresses. It is assumed that the network can prevent spoofing of IP addresses. User authentication is enabled via a traditional username-password mechanism (passwords are sent in clear-text). Encryption can be provided in multiple ways: via IPSec, via SSL or piggybacking over SSH using its port-forwarding mechanism. The third solution is a partial, non-independent solution that relies on SSH to provide encryption and authentication and assumes that users can Risso & Dutt Expires August 25, 2003 [Page 11] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 attempt sampling only over established SSH connections. This may not be acceptable in all circumstances. Currently defined authentication methods are: o NULL_AUTH: no authentication is required. o USRPWD_AUTH: username/password authentication is required. More advanced security mechanisms are currently under investigation. Risso & Dutt Expires August 25, 2003 [Page 12] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 5. RESCAP Messages This Section shows all the messages defined into the RESCAP protocol. 5.1 Authorization Message (Message Type = AUTH) The first message exchanged after a connection has been setup is the AUTH message. It is always sent by the collecting device to the sampling device. For instance, in the active mode the sampling device is only responsible for initiating the control connection. After this, it waits for the collecting device to send the AUTH Request. There are two currently defined authorization mechanisms: o Null authorization o Username and password If the sampling device does not accept the provided authorization, it sends back an ERROR message and it waits for another AUTH Request message. On a successful authorization, an AUTH Reply message is sent back. Figure 2 shows the format of the AUTH Request message, which is the payload part of Figure 1. 0 15 31 +---------------------------+---------------------------+ | Authentication Type | Unused | +---------------------------+---------------------------+ | First Auth Token Length | Second Auth Token Length | +---------------------------+---------------------------+ / Variable Length Authentication Token 1 / +-------------------------------------------------------+ / Variable Length Authentication Token 2 / +-------------------------------------------------------+ Figure 2: AUTH Request Message Format 5.2 Find All Interfaces Message (Message Type = FIND_ALL_INT) This message is used to obtain the list of interfaces on the target device. The definition of an interface is dependent on the device. For example, router and switches may list their connection to the switching fabric as an interface as well as all the physical ports. On network devices (switch and routers), these information can be Risso & Dutt Expires August 25, 2003 [Page 13] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 obtained by means of standard SNMP queries. However, workstation hosts do not have SNMP installed and this message provides a way to discover the interfaces (and their characteristics) on them. In case the collecting device alwady knows the interface list of the samping device (by means of SNMP queries), it can use the OPEN_SESSION command immediately. Figure 3 shows the format of the response to FIND_ALL_INT. The request is the basic protocol header with the type set to FIND_ALL_INT. The number of interfaces is returned in the Value field of the general header. 0 31 +-------------------------------------------------------+ / Information related to Interface 1 / +-------------------------------------------------------+ / Information related to Interface 2 / +-------------------------------------------------------+ / . . . / +-------------------------------------------------------+ / Information related to Interface N / +-------------------------------------------------------+ Figure 3: FIND_ALL_INT Reply Message Format Each interface will be returned with a set of operating parameters (the interface name, the description, the link-layer type) and the list of its network addresses. The format of the information provided for each interface is detailed in Figure 4, contained into the FIND_ALL_INT response message. Risso & Dutt Expires August 25, 2003 [Page 14] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 0 15 31 +---------------------------+---------------------------+ | Interface Name Length | Interface Descr. Length | +---------------------------+---------------------------+ | Number of Addresses | Link-Layer Type | +---------------------------+---------------------------+ / Interface Name / +-------------------------------------------------------+ / Interface Description / +-------------------------------------------------------+ / Information related to Address 1 / +-------------------------------------------------------+ / Information related to Address 2 / +-------------------------------------------------------+ / . . . / +-------------------------------------------------------+ / Information related to Address N / +-------------------------------------------------------+ Figure 4: Details of the fields related to a single interface The information about each interface address consists of: o the address (sockaddr_storage structure) o prefix length 5.3 Open RESCAP Session (Message Type = OPEN_SESSION) The OPEN_SESSION message is used to create a physical association between one sampling and one collecting process. Although no sampling has been started at the moment, this message allows selecting the interface on which the sampling has to be done. This message returns some parameters that are of interest for the following messages. The most important one is the SESSION_ID, which is an unique number (within the sampling device) associated to the current session. This permit to use that identifier in all the next messages instead of the interface name. This calls will trigger also the creation of the data connection. This is an advantage in case several sampling sessions will be started (one after the other) within the same SESSION_ID because the data connection is created only once. However, this document does not specify whether the sampling and the collecting processes have to be created in correspondence of this message. The creation of these processes is left to an implementation choice. Risso & Dutt Expires August 25, 2003 [Page 15] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 Figure 5 and Figure 6 show the format of the OPEN_SESSION request and response messages. The interface name contained into the Request message is a variable-length string; its length can be derived from the Length field, present in the General Header. In response to an OPEN_SESSION request, the target device returns an SESSION_ID that is used in subsequent control messages. 0 31 +-------------------------------------------------------+ / Interface Name / +-------------------------------------------------------+ Figure 5: OPEN_SESSION Request message 0 31 +-------------------------------------------------------+ | Session ID | +-------------------------------------------------------+ | Time Zone | +-------------------------------------------------------+ | Link-Layer Type | +-------------------------------------------------------+ Figure 6: OPEN_SESSION Reply message 5.4 Close Session (Message Type = CLOSE_SESSION) When the sampling device or the collecting device decide to close a previously opened session, they send a CLOSE_SESSION message. If a sampling session is in progress, it is immediately terminated. Typically, to just stop a sampling without closing the session, an END_SAMPLING message must be used. Figure 7 shows the format of the CLOSE_SESSION request message. The CLOSE_SESSION response message does not have a payload. The data connection is torn down in correspondence to this message. The control connection is still up instead. Risso & Dutt Expires August 25, 2003 [Page 16] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 0 31 +-------------------------------------------------------+ | Session ID | +-------------------------------------------------------+ Figure 7: CLOSE_SESSION Request message 5.5 Close RESCAP Connection (Message Type = CLOSE) This message is intended to close explicitely every connection between the sampling and collecting devices. This messages wants to avoid that a control connection is closed without informing the other end-party, leaving zombies on the remote device. Following this message, also the control connection has to be torn down. This message does not have payload since it does not transport any information. In case a sampling session is still open, this message will force the sampling ad collecting devices to perform all tasks related to the END_SAMPLING and CLOSE_SESSION messages as well. 5.6 Start Sampling (Message Type = START_SAMPLING) START_SAMPLING is the command that actually starts the sampling on an interface. Figure 8 shows the format of the request message. Some description of each of the fields is relevant: o Flags: it qualifies the sampling session with additional information that can be used to modify the behaviour of the process. The currently defined flags are: * SAMPFLAG_PROMISCUOUS: it sets the interface in promiscuous mode. This flag could be meaningless on switches and routers, but it is important in case of software worstation. * SAMPFLAG_UDP_DATA: it uses an UDP connection to send the sampled frames. If this is not set, TCP is used. * SAMPFLAG_PROBE_OPEN: the sampling device will attempt to open the data connection toward the collecting device. This is the default setting in case of Active Mode. * SAMPFLAG_INBOUND_ONLY: the sampling device will attempt to sample only inbound frames on the specified interface. This may not be supported on all devices and it is ignored in case the SAMPFLAG_PROMISCUOUS is set. * SAMPFLAG_OUTBOUND_ONLY: the sampling device will attempt to Risso & Dutt Expires August 25, 2003 [Page 17] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 sample only outbound frames on the specified interface. This may not be supported on all devices and it is ignored in case the SAMPFLAG_PROMISCUOUS is set. * SAMPFLAG_DELAYED_SEND: this option is to make the sampling device send all the selected frames only after the sampling process has been stopped. Based on the sampling buffer size, only the last set of bytes in the buffer can be sent. o Data Connection Port: it is used in active mode to indicate to the sampling device the port on which to establish the data connection toward the collecting device. The value of this field is meaningless in case the data connection is opened by the collecting device (which is the default behaviour in case of passive mode). o Session ID: it specifies the session this sampling command refers to. This value is tha one returned by the OPEN_SESSION message. o Snapshot Length: it specifies how many bytes of each packet must be saved. Only the first "snapshot_length" bytes are sent to the collecting device. A value of 0 implies the entire frame. o Sampling Buffer Size: this is a request to use a buffer of at least this size in KBytes (i.e. unit of 1024 bytes) in order to buffer packets to avoid drops due to a possible difference in the packet sampling rate and the packet transmission rate. The device returns the value that it is eventually used. o Max Number of Packets to Capture: it specifies how many packets are expected by the collecting device. A value of '0' implies that the sampling lasts till a END_SAMPLING message is received. o Max Size of Data to Capture: it specifies the maximum size of data that is expected by the collecting device, in KBytes (i.e. unit of 1024 bytes). This is useful in case the target device has a limited space and does not want to exceed a predetermined size. A value of '0' implies that the sampling lasts till a END_SAMPLING message is received. In case both "Max Number of Packets to Capture" and "Max Size of Data to Capture" are non-zero values, the sampling ends when the first threshold is reached. o Filtering Section: it is used to specify an initial filter that is setup before the sampling is started. The support of this is implementation-specific, dependent on the OS of the target device: some devices could not be able to filter packets. The format of this Section is specified in Section 5.6.1. Risso & Dutt Expires August 25, 2003 [Page 18] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 o Sampling Information Section: this keeps some additional information related to the sampling process (e.g. the sampling mode, etc). The format of this Section is specified in Section 5.6.2. o Data Connection Information Section: this keeps some additional information related to the data connection (for example if the data connection does not have to exceed a given rate, or such). The format of this Section is specified in Section 5.6.3. 0 15 31 +---------------------------+---------------------------+ | Flags | Data Connection Port | +---------------------------+---------------------------+ | Session ID | +-------------------------------------------------------+ | Snapshot Length | +-------------------------------------------------------+ | Sampling Buffer Size | +-------------------------------------------------------+ | Max Number of Packets to Capture | +-------------------------------------------------------+ | Max Size of Data to Capture | +-------------------------------------------------------+ / Filtering Section / +-------------------------------------------------------+ / Sampling Information Section / +-------------------------------------------------------+ / Data Connection Information Section / +-------------------------------------------------------+ Figure 8: START_SAMPLING Request Message Figure 9 shows the format of the START_SAMPLING Response if successful. There is no negotiation performed with respect to the parameters. The client specifies its desired values and the server responds with what it can support. If the client does not like the values returned by the server, it can end the sampling session. The Data Connection Port field is used in case the collecting device is going to open the data connection toward the sampling device. In this case, the sampling device will tell the port number on which is going to accept the connection. This port is allocated dynamically in order to make easier the recognition of a new incoming data connection on the target device. A dynamic allocation solves the problem of a device that has two processes waiting for an incoming data connection, which will arrive both on the same destination port. Risso & Dutt Expires August 25, 2003 [Page 19] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 0 15 31 +---------------------------+---------------------------+ | Flags | Data Connection Port | +---------------------------+---------------------------+ | Session ID | +-------------------------------------------------------+ | Sampling Buffer Size | +-------------------------------------------------------+ Figure 9: START_SAMPLING Reply Message 5.6.1 Filtering Section This format is used to specify the filter used during the sampling process. 5.6.2 Sampling Information Section This format is used to specify the sampling method (and parameters) used in the current sampling process. 5.6.3 Data Connection Information Section This format is used to specify the information related to the data connection (e.g. the maximum speed used to send data to the collecting device). 5.7 End Sampling (Message Type = END_SAMPLING) This is used to terminate an existing sampling. The SESSION_ID on which the sampling session must be stopped is specified in the request message. The message format is shown in Figure 10. 0 31 +-------------------------------------------------------+ | Session ID | +-------------------------------------------------------+ Figure 10: END_SAMPLING Request message In response to the END_SAMPLING message, the target device returns the message shown in Figure 11, which includes some statistics in the format shown in figure in Figure 13. Risso & Dutt Expires August 25, 2003 [Page 20] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 0 31 +-------------------------------------------------------+ | Session ID | +-------------------------------------------------------+ / Sampling Statistics Section / +-------------------------------------------------------+ Figure 11: END_SAMPLING Reply message 5.8 Adjust Sampling Parameters (Message Type = ADJUST_SAMPLING_PARS) This message is used to change some of the current parameters of the capture (filter, samping information, data connection parameters). 5.9 Get Sampling Statistics (Message Type = GET_SAMPLING_STATS) This message is used to obtain statistics related to an existing capture session. The format of the request message is shown in Figure 12. The information provided by the GET_SAMPLING_STATS Reply can be retrieved by other ways (for example through SNMP queries). However, workstations hosts do not usually have SNMP installed; this message enables these devices to get the most relevant statistical information. 0 31 +-------------------------------------------------------+ | Session ID | +-------------------------------------------------------+ Figure 12: GET_SAMPLING_STATS Request message The format of the response is shown in Figure 13. The fields contained into the Reply message are: o Packets Dropped by Interface: it gives the number of packets dropped by the physical interface due to lack of resources. Although this parameter is meaningless on router and switches, it represents a possible event in case of software capture. This happens indeed when the capturing workstation is overhelmed by packets and the operating system is not able to give service to the high number of interrupts arriving from the network card. o Packets Successfully Received by Interface: it represent the total number of packets that have been succesfully received by the Risso & Dutt Expires August 25, 2003 [Page 21] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 network interface. This number depends on the flags selected for the capture. For instance, if the current section captures only inbound packets (flag CAPFLAG_INBOUND_ONLY) this number takes into accounts the total number of inbound packets received by the interface. o Packets Submitted to the Filter: it keeps the actual number of packets that have been selected by the sampling mechanism and that have been submitted to the filtering engine. o Packets Matching the filter: it represents the total number of packets that satisfy the filter. o Packets Dropped After Filtering: after applying a filtering function, the sampling process sends the packet to the collecting process. However, for several reasons, this delivery might not be done immediately and the packets must be temporarily stored into the sampling buffer for a delayed delivery. This counter gives the number of packets that have been dropped due to lack of resources (e.g. lack of space into the sampling buffer) before being able to send them to the collecting process. o Packets Transmitted to the Collecting Device: it represents the total number of packets that have been transmitted to the collecting device. This number can be derived from the number of packets that matched the filter minus the number of packets dropped after filtering and the ones that are actually stored into the sampling buffer (and that are still waiting to be transmitted). It is worth noticing that this number can be higher than the number of packets received by the collecting device, since there can be some packets "in flight" into the network. All the previous numbers refer from the instant of time in which the sampling began to the instant of time in which the statistics have been requested to the sampling process. Risso & Dutt Expires August 25, 2003 [Page 22] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 0 31 +-------------------------------------------------------+ | Packets Dropped by Interface | +-------------------------------------------------------+ | Packets Successfully Received by Interface | +-------------------------------------------------------+ | Packets Submitted to the Filter | +-------------------------------------------------------+ | Packets Matching the filter | +-------------------------------------------------------+ | Packets Dropped After Filtering | +-------------------------------------------------------+ | Packets Transmitted to the Collecting Device | +-------------------------------------------------------+ Figure 13: GET_SAMPLING_STATS Reply message 5.10 Error Message (Message Type = ERROR) In case of an error in processing any of the commands listed before, the response is a message called ERROR message. This message does not have the Request and Reply form and it comes only as a Reply. The format of this message is shown in Figure 14. 0 15 31 +---------------------------+---------------------------+ | Error Code | Unused | +---------------------------+---------------------------+ | Session ID | +-------------------------------------------------------+ / Error String / +-------------------------------------------------------+ Figure 14: ERROR Message The Error Code field keeps the numeric code of the error occurred, while the Error String keeps a string description of the error. The length of the error string can be derived from the length of the RESCAP payload, contained into the general header. Risso & Dutt Expires August 25, 2003 [Page 23] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 6. RESCAP Codes and Values This section lists all the codes and the values that have been allocated to the RESCAP Protocol. Protocol Ports The port on which the sampling device waits for connection is . Timers The values for the RESCAP timer are the following: * INIT_TIMEOUT: 30 sec. * RUN_TIMEOUT: 90 sec. Protocol Messages The codes used for RESCAP protocol messages are the following: * AUTH: code 1. * FIND_ALL_INT: code 2. * OPEN_SESSION: code 3. * CLOSE_SESSION: code 4. * CLOSE: code 5. * START_SAMPLING: code 6. * END_SAMPLING: code 7. * UPDATE_SAMPLING_PARS: code 8. * GET_SAMPLING_STATS: code 9. * ERROR: code 10. Protocol Flags The flags used in some messages of the RESCAP protocols assume the following values: * Authentication Types The types of authentication currently supported are: * NULL_AUTH: code 1. Risso & Dutt Expires August 25, 2003 [Page 24] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 * USRPWD_AUTH: code 2. Error Codes The types of error codes currently supported are: * Authors' Addresses Fulvio Risso Politecnico di Torino Corso Duca degli Abruzzi, 24 Torino 10129 Italy Phone: +39 011 564 7008 EMail: fulvio.risso@polito.it URI: http://www.polito.it/~risso/ Dinesh Dutt Cisco Systems 375 East Tasman Drive San Jose, CA 95134 US Phone: +1 408 527 0955 EMail: ddutt@cisco.com Risso & Dutt Expires August 25, 2003 [Page 25] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. Full Copyright Statement Copyright (C) The Internet Society (2003). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assignees. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION Risso & Dutt Expires August 25, 2003 [Page 26] Internet-Draft REmote Sample and CApture Protocol (RESCAP) February 2003 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Risso & Dutt Expires August 25, 2003 [Page 27]