Fortinet black logo

CLI Reference

server-policy persistence-policy

server-policy persistence-policy

Use this command to configure a persistence method and timeout that you can apply to server pools. The persistence policy applies to all members of the server pool.

After FortiWeb has forwarded the first packet from a client to a pool member, some protocols require that subsequent packets also be forwarded to the same back-end server until a period of time passes or the client indicates that it has finished transmission.

To apply a persistence policy, select it when you configure a server pool. For details, see server-policy server-pool.

To use this command, your administrator account’s access control profile must have either w or rw permission to the traroutegrp area. For details, see Permissions.

Syntax

config server-policy persistence-policy

edit "<persistence-policy_name>"

set type { source-ip | persistent-cookie | asp-sessionid | php-sessionid | jsp-sessionid | insert-cookie | http-header | url-parameter | rewrite-cookie | embedded-cookie | ssl-session-id }

set cookie-name "<cookie-name_str>"

set timeout "<timeout_int>"

set ipv4-netmask "<v4mask>"

set ipv6-mask-length "<v6mask>"

set http-header "<http-header_str>"

set url-parameter "<url-parameter_str>"

set cookie-path "<cookie-path_str>"

set cookie-domain "<cookie-domain_str>"

set secure-cookie {enable | disable}

next

end

Variable Description Default

"<persistence-policy_name>"

Enter the name of the persistence policy. The maximum length is 63 characters.

To display the list of existing persistence policies, enter:

edit ?

No default.

type { source-ip | persistent-cookie | asp-sessionid | php-sessionid | jsp-sessionid | insert-cookie | http-header | url-parameter | rewrite-cookie | embedded-cookie | ssl-session-id }

  • source-ip—Forwards subsequent requests with the same client IP address and subnet as the initial request to the same pool member. To define how FortiWeb derives the appropriate subnet from the IP address, configure ipv4-netmask "<v4mask>" and ipv6-mask-length "<v6mask>".
  • persistent-cookie—If an initial request contains a cookie whose name matches the cookie-name "<cookie-name_str>" value, FortiWeb forwards subsequent requests that contain the same cookie value to the same pool member as the initial request.
  • asp-sessionid—If a cookie in the initial request contains an ASP .NET session ID value, FortiWeb forwards subsequent requests with the same session ID value to the same pool member as the initial request. FortiWeb preserves the original cookie name.
  • php-sessionid—If a cookie in the initial request contains a PHP session ID value, FortiWeb forwards subsequent requests with the same session ID value to the same pool member as the initial request. FortiWeb preserves the original cookie name.
  • jsp_sessionidFortiWeb forwards subsequent requests with the same JSP session ID as the inital request to the same pool member. FortiWeb preserves the original cookie name.
  • insert-cookieFortiWeb inserts a cookie with the name specified by cookie-name "<cookie-name_str>" to the initial request and forwards all subsequent requests with this cookie to the same pool member. FortiWeb uses this cookie for persistence only and does not forward it to the pool member. Also specify cookie-path "<cookie-path_str>" and cookie-domain "<cookie-domain_str>".
  • http-header—Forwards subsequent requests with the same value for an HTTP header as the initial request to the same pool member. Also configure http-header.
source-ip
  • url-parameter—Forwards subsequent requests with the same value for a URL parameter as the initial request to the same pool member. Also configure url-parameter.
  • rewrite-cookie—If the HTTP response has a Set-Cookie: value that matches the value specified by cookie-name "<cookie-name_str>", FortiWeb replaces the value with a randomly generated cookie value. FortiWeb forwards all subsequent requests with this generated cookie value to the same pool member.
  • embedded-cookie—If the HTTP response contains a cookie with the name specified by cookie-name "<cookie-name_str>", FortiWeb preserves the original cookie value and adds a randomly generated cookie value and a ~ (tilde) as a prefix. FortiWeb forwards all subsequent requests with this cookie and prefix to the same pool member.
  • ssl-session-id—If a cookie in the initial request contains an SSL session ID value, FortiWeb forwards subsequent requests with the same session ID value to the same pool member as the initial request. FortiWeb preserves the original cookie name.

For persistence types that use cookies, you can use the sessioncookie-enforce setting to maintain persistence for transactions within a session. For details, see server-policy policy.

cookie-name "<cookie-name_str>"

Enter a value to match or the name of the cookie that FortiWeb inserts.

Available only when the persistence type uses a cookie.

No default.

timeout "<timeout_int>"

Enter the maximum amount of time between requests that FortiWeb maintains persistence, in seconds.

FortiWeb stops forwarding requests according to the established persistence after this amount of time has elapsed since it last received a request from the client with the associated property (for example, an IP address or cookie). Instead, it again selects a pool member using the load balancing method specified in the server pool configuration.

300

ipv4-netmask "<v4mask>"

Enter the IPv4 subnet used for session persistence.

For example, if IPv4 Netmask is 256.256.256.256, FortiWeb can forward requests from IP addresses 192.0.2.1 and 192.0.2.2 to different server pool members.

If IPv4 Netmask is 256.256.256.0, FortiWeb forwards requests from IP addresses 192.0.2.1 and 192.0.2.2 to the same pool member.

256.256.256.256

ipv6-mask-length "<v6mask>"

Enter the IPv6 network prefix used for session persistence. 128

http-header "<http-header_str>"

Enter the name of the HTTP header that the persistence feature uses to route requests. No default.

url-parameter "<url-parameter_str>"

Enter the name of the URL parameter that the persistence feature uses to route requests. No default.

cookie-path "<cookie-path_str>"

Enter a path attribute for the cookie that FortiWeb inserts, if type { source-ip | persistent-cookie | asp-sessionid | php-sessionid | jsp-sessionid | insert-cookie | http-header | url-parameter | rewrite-cookie | embedded-cookie | ssl-session-id } is insert-cookie. No default.

cookie-domain "<cookie-domain_str>"

Enter a domain attribute for the cookie that FortiWeb inserts, if type { source-ip | persistent-cookie | asp-sessionid | php-sessionid | jsp-sessionid | insert-cookie | http-header | url-parameter | rewrite-cookie | embedded-cookie | ssl-session-id } is insert-cookie. No default.

secure-cookie {enable | disable}

Configure the secure cookie to force browsers to return the cookie only for HTTPS traffic.

disable

Example

This example creates the persistence policy ip-persistence. When this policy is applied to a server pool, FortiWeb forwards initial requests from an IP address using the load-balancing algorithm configured for the pool. It forwards any subsequent requests with the same client IP address as the initial request to the same pool member. After FortiWeb has not received a request from the IP address for 400 seconds, it forwards any subsequent initial requests from the IP address using the load-balancing algorithm.

config server-policy persistence-policy

edit "ip-persistence"

set type source-ip

set timeout 400

next

end

Related topics

server-policy persistence-policy

Use this command to configure a persistence method and timeout that you can apply to server pools. The persistence policy applies to all members of the server pool.

After FortiWeb has forwarded the first packet from a client to a pool member, some protocols require that subsequent packets also be forwarded to the same back-end server until a period of time passes or the client indicates that it has finished transmission.

To apply a persistence policy, select it when you configure a server pool. For details, see server-policy server-pool.

To use this command, your administrator account’s access control profile must have either w or rw permission to the traroutegrp area. For details, see Permissions.

Syntax

config server-policy persistence-policy

edit "<persistence-policy_name>"

set type { source-ip | persistent-cookie | asp-sessionid | php-sessionid | jsp-sessionid | insert-cookie | http-header | url-parameter | rewrite-cookie | embedded-cookie | ssl-session-id }

set cookie-name "<cookie-name_str>"

set timeout "<timeout_int>"

set ipv4-netmask "<v4mask>"

set ipv6-mask-length "<v6mask>"

set http-header "<http-header_str>"

set url-parameter "<url-parameter_str>"

set cookie-path "<cookie-path_str>"

set cookie-domain "<cookie-domain_str>"

set secure-cookie {enable | disable}

next

end

Variable Description Default

"<persistence-policy_name>"

Enter the name of the persistence policy. The maximum length is 63 characters.

To display the list of existing persistence policies, enter:

edit ?

No default.

type { source-ip | persistent-cookie | asp-sessionid | php-sessionid | jsp-sessionid | insert-cookie | http-header | url-parameter | rewrite-cookie | embedded-cookie | ssl-session-id }

  • source-ip—Forwards subsequent requests with the same client IP address and subnet as the initial request to the same pool member. To define how FortiWeb derives the appropriate subnet from the IP address, configure ipv4-netmask "<v4mask>" and ipv6-mask-length "<v6mask>".
  • persistent-cookie—If an initial request contains a cookie whose name matches the cookie-name "<cookie-name_str>" value, FortiWeb forwards subsequent requests that contain the same cookie value to the same pool member as the initial request.
  • asp-sessionid—If a cookie in the initial request contains an ASP .NET session ID value, FortiWeb forwards subsequent requests with the same session ID value to the same pool member as the initial request. FortiWeb preserves the original cookie name.
  • php-sessionid—If a cookie in the initial request contains a PHP session ID value, FortiWeb forwards subsequent requests with the same session ID value to the same pool member as the initial request. FortiWeb preserves the original cookie name.
  • jsp_sessionidFortiWeb forwards subsequent requests with the same JSP session ID as the inital request to the same pool member. FortiWeb preserves the original cookie name.
  • insert-cookieFortiWeb inserts a cookie with the name specified by cookie-name "<cookie-name_str>" to the initial request and forwards all subsequent requests with this cookie to the same pool member. FortiWeb uses this cookie for persistence only and does not forward it to the pool member. Also specify cookie-path "<cookie-path_str>" and cookie-domain "<cookie-domain_str>".
  • http-header—Forwards subsequent requests with the same value for an HTTP header as the initial request to the same pool member. Also configure http-header.
source-ip
  • url-parameter—Forwards subsequent requests with the same value for a URL parameter as the initial request to the same pool member. Also configure url-parameter.
  • rewrite-cookie—If the HTTP response has a Set-Cookie: value that matches the value specified by cookie-name "<cookie-name_str>", FortiWeb replaces the value with a randomly generated cookie value. FortiWeb forwards all subsequent requests with this generated cookie value to the same pool member.
  • embedded-cookie—If the HTTP response contains a cookie with the name specified by cookie-name "<cookie-name_str>", FortiWeb preserves the original cookie value and adds a randomly generated cookie value and a ~ (tilde) as a prefix. FortiWeb forwards all subsequent requests with this cookie and prefix to the same pool member.
  • ssl-session-id—If a cookie in the initial request contains an SSL session ID value, FortiWeb forwards subsequent requests with the same session ID value to the same pool member as the initial request. FortiWeb preserves the original cookie name.

For persistence types that use cookies, you can use the sessioncookie-enforce setting to maintain persistence for transactions within a session. For details, see server-policy policy.

cookie-name "<cookie-name_str>"

Enter a value to match or the name of the cookie that FortiWeb inserts.

Available only when the persistence type uses a cookie.

No default.

timeout "<timeout_int>"

Enter the maximum amount of time between requests that FortiWeb maintains persistence, in seconds.

FortiWeb stops forwarding requests according to the established persistence after this amount of time has elapsed since it last received a request from the client with the associated property (for example, an IP address or cookie). Instead, it again selects a pool member using the load balancing method specified in the server pool configuration.

300

ipv4-netmask "<v4mask>"

Enter the IPv4 subnet used for session persistence.

For example, if IPv4 Netmask is 256.256.256.256, FortiWeb can forward requests from IP addresses 192.0.2.1 and 192.0.2.2 to different server pool members.

If IPv4 Netmask is 256.256.256.0, FortiWeb forwards requests from IP addresses 192.0.2.1 and 192.0.2.2 to the same pool member.

256.256.256.256

ipv6-mask-length "<v6mask>"

Enter the IPv6 network prefix used for session persistence. 128

http-header "<http-header_str>"

Enter the name of the HTTP header that the persistence feature uses to route requests. No default.

url-parameter "<url-parameter_str>"

Enter the name of the URL parameter that the persistence feature uses to route requests. No default.

cookie-path "<cookie-path_str>"

Enter a path attribute for the cookie that FortiWeb inserts, if type { source-ip | persistent-cookie | asp-sessionid | php-sessionid | jsp-sessionid | insert-cookie | http-header | url-parameter | rewrite-cookie | embedded-cookie | ssl-session-id } is insert-cookie. No default.

cookie-domain "<cookie-domain_str>"

Enter a domain attribute for the cookie that FortiWeb inserts, if type { source-ip | persistent-cookie | asp-sessionid | php-sessionid | jsp-sessionid | insert-cookie | http-header | url-parameter | rewrite-cookie | embedded-cookie | ssl-session-id } is insert-cookie. No default.

secure-cookie {enable | disable}

Configure the secure cookie to force browsers to return the cookie only for HTTPS traffic.

disable

Example

This example creates the persistence policy ip-persistence. When this policy is applied to a server pool, FortiWeb forwards initial requests from an IP address using the load-balancing algorithm configured for the pool. It forwards any subsequent requests with the same client IP address as the initial request to the same pool member. After FortiWeb has not received a request from the IP address for 400 seconds, it forwards any subsequent initial requests from the IP address using the load-balancing algorithm.

config server-policy persistence-policy

edit "ip-persistence"

set type source-ip

set timeout 400

next

end

Related topics