ltm rule command TCP option

iRule(1)					  BIG-IP TMSH Manual					     iRule(1)

TCP::option
       Retrieves or changes TCP header options.

SYNOPSIS
       TCP::option ((get TCP_OPTION)	|
			    (noset TCP_OPTION)	|
			    (set TCP_OPTION VALUE (next | all)))

DESCRIPTION
       Gets or sets the value of the specified option of the TCP header.  The TCP::option get command is only
       functional when BIG-IP has been configured to collect options before the iRule is called. In v10, this is done
       with a db variable and is effective only on the clientside. When called in the serverside context it returns
       an error indicating that the specified option was not configured for collection.

       In v11, this is configured through the TCP profile and the command can be used in either the serverside
       context or the clientside, depending on the profile configuration. TCP::option set is available only in v11
       and can be used in either context.

       Syntax

       TCP::option get 

	    * Returns the specified TCP option kind value. If the requested
	      option kind was not configured for collection, an error indicating
	      so is returned instead. If the option kind was specified but has
	      not yet been seen on the current connection, the command returns
	      null. If the requested option kind has been configured for
	      collection and has been seen on the connection, the command returns
	      the raw option kind value. See version-specific sections below
	      regarding configuring option kinds for collection.

       TCP::option set   

	    * Introduced in v11
	    * Allows you to set (or add) TCP option information for the specified
	      option field

       TCP::option noset 

	    * Introduced in v11
	    * Allows you to specify particular TCP options that should not be
	      set.

       Configuring for TCP option collection - BIG-IP version >= 10.2.0-HF2 and < 11.0.0

	  The Rules.tcpoption.settings database variable must be configured in
	  order to use the TCP::option command in 10.2.0HF2 < 11.0, specifying
	  the option values to be collected. In TMOS versions 10.2.0 HF2 through
	  10.2.2, the BIG-IP system must be restarted using the bigstart restart
	  command after setting or modifying the variable. Starting with release
	  10.2.2 HF1 the restart is no longer required.
	  Configure the db variable Rules.Tcpoption.settings with a string in the
	  following format:
	  [option,],[option,],[option,]...

	  Note: Do not change the unrelated db setting Rules.tcpoption.virtuals
	  from its default value of null in 10.2.0-hf2. This will cause tmm to
	  repeatedly restart.

       Configuring for TCP option collection - BIG-IP version 11.0.0 and up

	  Beginning with v11.0.0 the 'db variable Rules.TCPoption.settings' no
	  longer exists and this functionality has been 'baked in'. It is now
	  part of the tcp profile and is configured as follows:

	  create ltm profile tcp PROFILE_NAME tcp-options "{option } {option}"
	     option
		* A number between 2 and 255 (inclusive) that indicates the TCP
		  option kind to be collected.

	     first | last
		* Indicates whether the system will retain the first instance of the
		  specified option kind, or the most recent.

	  When an option kind is marked first, the system will search for the
	  specified option kind only until it has been seen on the current
	  connection. Once seen, the TCP::option command will return that value
	  for the life of the connection.

	  When an option kind is marked last, the system will continue to search
	  for the specified option kind over the lifetime of the connection. The
	  TCP::option command will return the last value seen at the time it is
	  called.

	  If all option kinds are marked first, and all specified option kinds
	  have been seen on that TCP connection, no further searching will be
	  performed for the life of the connection.

	  For example, the following command configures the BIG-IP system to save
	  the value of the first instance of option kind 8, and the value of the
	  last seen instance of option kind 28:
	   v10: b db Rules.Tcpoption.settings [8,first],[28,last]
	   v11: create ltm profile tcp tcp_options profile-name "{8 first} {28
	  last}"

RETURN VALUE
       With the "get" keyword, returns the specified TCP option kind value. If the requested option kind was not
       configured for collection, an error indicating so is returned instead. If the option kind was specified but
       has not yet been seen on the current connection, the command returns null. If the requested option kind has
       been configured for collection and has been seen on the connection, the command returns the raw option kind
       value.

VALID DURING
       CLIENT_ACCEPTED, CLIENT_CLOSED, CLIENT_DATA, SERVER_INIT, SERVER_CLOSED, SERVER_CONNECTED, SERVER_DATA,
       SIP_REQUEST, SIP_REQUEST_SEND, SIP_RESPONSE, STREAM_MATCHED

EXAMPLES
	#Accessing TCP Options
	when CLIENT_ACCEPTED {
	  set INPUT_OPTION [TCP::option get 28]
	  binary scan $INPUT_OPTION c ver
	  set ver [expr { $ver & 0xff }]
	  set forwarded_ip [IP::addr parse $INPUT_OPTION 1]
	  log local0. "The IP address was $forwarded_ip for version $ver"
	}

	#Insert the client REAL IP (mostly used when the client IP is SNATted).
	when SERVER_CONNECTED {
	    scan [IP::client_addr] {%d.%d.%d.%d} a b c d
	    TCP::option set 29 [binary format cccc $a $b $c $d] all
	}

HINTS
SEE ALSO
CHANGE LOG
       @BIGIP-10.2.0-HF2 --First introduced the command.

BIG-IP						      2020-06-23					     iRule(1)