<!-- review: finished -->

<a id="http-userid"></a>

# UserID

The module sets cookies suitable for client identification. Received and set cookies can be logged using the built-in variables [$uid_got](#v-uid-got) and [$uid_set](#v-uid-set). This module is compatible with the [mod_uid](http://www.lexa.ru/programs/mod-uid.html) module for Apache.

<a id="configuration-example-47"></a>

## Configuration Example

```nginx
userid         on;
userid_name    uid;
userid_domain  example.com;
userid_path    /;
userid_expires 365d;
userid_p3p     'policyref="/w3c/p3p.xml", CP="CUR ADM OUR NOR STA NID"';
```

<a id="directives-50"></a>

## Directives

<a id="index-0"></a>

<a id="id1"></a>

### userid

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid` `on` | `v1` | `log` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `userid off;`                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Enables or disables setting cookies and logging the received cookies:

| `on`   | enables the setting of version 2 cookies and logging of the received cookies;   |
|--------|---------------------------------------------------------------------------------|
| `v1`   | enables the setting of version 1 cookies and logging of the received cookies;   |
| `log`  | disables the setting of cookies, but enables logging of the received cookies;   |
| `off`  | disables the setting of cookies and logging of the received cookies.            |

<a id="index-1"></a>

<a id="userid-domain"></a>

### userid_domain

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_domain` name | `none`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `userid_domain none;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location           |

Defines a domain for which the cookie is set. The `none` parameter disables setting of a domain for the cookie.

<a id="index-2"></a>

<a id="userid-expires"></a>

### userid_expires

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_expires` time | `max` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `userid_expires off;`                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Sets a time during which a browser should keep the cookie. The parameter `max` will cause the cookie to expire on "31 Dec 2037 23:55:55 GMT". The parameter `off` will cause the cookie to expire at the end of a browser session.

<a id="index-3"></a>

<a id="userid-flags"></a>

### userid_flags

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_flags` `off` | flag ...;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `userid_flags off;`                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

If the parameter is not `off`, defines one or more additional flags for
the cookie: `secure`, `httponly`, `samesite=strict`,
`samesite=lax`, `samesite=none`.

<a id="index-4"></a>

<a id="userid-mark"></a>

### userid_mark

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_mark` letter | digit | = | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `userid_mark off;`                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                      |

If the parameter is not `off`, enables the cookie marking mechanism and sets the character used as a mark. This mechanism is used to add or change [userid_p3p](#userid-p3p) and/or a cookie expiration time while preserving the client identifier. A mark can be any letter of the English alphabet (case-sensitive), digit, or the "=" character.

If the mark is set, it is compared with the first padding symbol in the base64 representation of the client identifier passed in a cookie. If they do not match, the cookie is resent with the specified mark, expiration time, and `P3P` header.

<a id="index-5"></a>

<a id="userid-name"></a>

### userid_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_name` name;    |
|------------------------------------------------------------------------------------------|------------------------|
| Default                                                                                  | `userid_name uid;`     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location |

Sets the cookie name.

<a id="index-6"></a>

<a id="userid-p3p"></a>

### userid_p3p

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_p3p` string | `none`;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | `userid_p3p none;`              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

Sets a value for the `P3P` header field that will be sent along with the cookie. If the directive is set to the special value `none`, the `P3P` header will not be sent in a response.

<a id="index-7"></a>

<a id="userid-path"></a>

### userid_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_path` path;    |
|------------------------------------------------------------------------------------------|------------------------|
| Default                                                                                  | `userid_path /;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location |

Defines a path for which the cookie is set.

<a id="index-8"></a>

<a id="userid-service"></a>

### userid_service

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_service` number;                   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | `userid_service IP address of the server;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                     |

If identifiers are issued by multiple servers (services), each service should be assigned its own `number` to ensure that client identifiers are unique. For version 1 cookies, the default value is zero. For version 2 cookies, the default value is the number composed from the last four octets of the server's IP address.

<a id="built-in-variables-16"></a>

## Built-in Variables

<a id="v-uid-got"></a>

### `$uid_got`

The cookie name and received client identifier.

<a id="v-uid-reset"></a>

### `$uid_reset`

If the variable is set to a non-empty string that is not `0`, the client identifiers are reset. The special value `log` additionally leads to the output of messages about the reset identifiers to the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).

<a id="v-uid-set"></a>

### `$uid_set`

The cookie name and sent client identifier.