# &adminguide;

## Overview

The module contains REGISTER processing logic.

### PATH support

Register module includes Path support (according to RFC 3327) for usage in registrars and home-proxies.

A call to save(...) stores, if path-support is enabled in the registrar-module, the values of the Path Header(s) along with the contact into usrloc. There are three modes regarding the reply to a REGISTER including one or more Path HFs:

- off - stores the value of the Path headers into usrloc without passing it back to the UAC in the reply.

- lazy - stores the Path header and passes it back to the UAC if Path-support is indicated by the path param in the Supported HF.

- strict - rejects the registration with 420 Bad Extension if there's a Path header but no support for it is indicated by the UAC. Otherwise it's stored and passed back to the UAC.

A call to lookup(...) always uses the path header if found, and inserts it as Route HF either in front of the first Route HF, or after the last Via HF if no Route is present. It also sets the destination uri to the first Path uri, thus overwriting the received-uri, because NAT has to be handled at the outbound-proxy of the UAC (the first hop after client's NAT).

The whole process is transparent to the user, so no config changes are required beside setting the registrar-parameters use_path and path_mode.

### GRUU support

Register module includes GRUU support (according to RFC 5627) for usage in registrars and home-proxies.

A call to save(...) stores, if the phone supports GRUU, the values of the SIP Instance along with the contact into usrloc. The registrar module will generate two types of GRUUs :

- public - exposes the underlying AOR, constructed just by attaching the SIP Instance as the ;gr parameter value. These are persistent, valid as long as the contact registration is valid.

- temporary - hides the underlying AOR Each new Register request leads to the construction of a new temporary GRUU, while Register requests with a different Call-Id lead to the invalidation of all the previous generated temporary GRUUs.

A call to lookup(...) will try to detect if the R-URI contains a GRUU. If it does, it will route the request just for the Contact that the specific AOR belongs to, without appending any other branches.

The whole process is transparent to the user, so no config changes are required.

## Dependencies

### &osips; Modules

The following modules must be loaded before this module:

- usrloc - User Location Module.

- signaling - Signaling module.

### External Libraries or Applications

The following libraries or applications must be installed before running &osips; with this module loaded:

- None.

## Exported Parameters

### `default_expires` (integer)

If the processed message contains neither Expires HFs nor expires contact parameters, this value will be used for newly created usrloc records. The parameter contains number of second to expire (for example use 3600 for one hour).

Default value is 3600.

#### Set `default_expires` parameter

    ...
    modparam("registrar", "default_expires", 1800)
    ...

### `min_expires` (integer)

The minimum expires value of a Contact, values lower than this minimum will be automatically set to the minimum. Value 0 disables the checking.

Default value is 60.

#### Set `min_expires` parameter

    ...
    modparam("registrar", "min_expires", 60)
    ...

### `max_expires` (integer)

The maximum expires value of a Contact, values higher than this maximum will be automatically set to the maximum. Value 0 disables the checking.

Default value is 0.

#### Set `max_expires` parameter

    ...
    modparam("registrar", "max_expires", 120)
    ...

### `default_q` (integer)

The parameter represents default q value for new contacts. Because &osips; doesn't support float parameter types, the value in the parameter is divided by 1000 and stored as float. For example, if you want default_q to be 0.38, use value 380 here.

Default value is 0.

#### Set `default_q` parameter

    ...
    modparam("registrar", "default_q", 1000)
    ...

### `tcp_persistent_flag` (integer)

The parameter specifies the message flag to be used to control the module behaviour regarding TCP connections. If the flag is set for a REGISTER via TCP containing a TCP contact, the module, via the save() function, will set the lifetime of the TCP connection to the contact expire value. By doing this, the TCP connection will stay on as long as the contact is valid.

Default value is -1 (disabled).

#### Set `tcp_persistent_flag` parameter

    ...
    modparam("registrar", "tcp_persistent_flag", 7)
    ...

### `realm_prefix` (string)

Prefix to be automatically strip from realm. As an alternative to SRV records (not all SIP clients support SRV lookup), a subdomain of the master domain can be defined for SIP purposes (like sip.mydomain.net pointing to same IP address as the SRV record for mydomain.net). By ignoring the realm_prefix "sip.", at registration, sip.mydomain.net will be equivalent to mydomain.net .

Default value is NULL (none).

#### Set `realm_prefix` parameter

    ...
    modparam("registrar", "realm_prefix", "sip.")
    ...

### `case_sensitive` (integer)

If set to 1 then AOR comparison will be case sensitive (as RFC3261 instructs), if set to 0 then AOR comparison will be case insensitive.

Default value is 1.

#### Set `case_sensitive` parameter

    ...
    modparam("registrar", "case_sensitive", 0)
    ...

### `received_avp` (str)

Registrar will store the value of the AVP configured by this parameter in the received column in the user location database. It will leave the column empty if the AVP is empty. The AVP should contain a SIP URI consisting of the source IP, port, and protocol of the REGISTER message being processed.

The value of this parameter should be the same as the value of corresponding parameter of nathelper module.

Default value is "NULL" (disabled).

#### Set `received_avp` parameter

    ...
    modparam("registrar", "received_avp", "$avp(rcv)")
    ...

### `received_param` (string)

The name of the parameter that will be appended to Contacts of 200 OK when the received URI was set by nathelper module.

Default value is "received".

#### Set `received_param` parameter

    ...
    modparam("registrar", "received_param", "rcv")
    ...

### `max_contacts` (integer)

The parameter can be used to limit the number of contacts per AOR (Address of Record) in the user location database. Value 0 disables the check.

This is the default value and will be used only if no other value (for max_contacts) is passed as parameter to the save() function. That's it - the function parameter overwride this global parameter.

Default value is 0.

#### Set `max_contacts` parameter

    ...
    # Allow no more than 10 contacts per AOR
    modparam("registrar", "max_contacts", 10)
    ...

### `retry_after` (integer)

The registrar can generate 5xx reply to REGISTER in various situations. It can, for example, happen when the `max_contacts` parameter is set and the processing of REGISTER request would exceed the limit. In this case the registrar would generate "503 Service Unavailable" response.

If you want to add the Retry-After header field in 5xx replies, set this parameter to a value grater than zero (0 means do not add the header field). See section 20.33 of RFC3261 for more details.

Default value is 0 (disabled).

#### Set `retry_after` parameter

    ...
    modparam("registrar", "retry_after", 30)
    ...

### `sock_hdr_name` (string)

Header which contains a socket description (proto:IP:port) to override the received socket info. The header will be search and used only if the flag 's' (Socket header) is set at "save()" time.

This makes sense only in multiple replicated servers scenarios.

Default value is NULL.

#### Set `sock_hdr_namer` parameter

    ...
    modparam("registrar", "sock_hdr_name", "Sock-Info")
    ...

### `mcontact_avp` (string)

AVP to store the modified binding that is set during cached registrations scenario (when REGISTER is forwarded to another registrar). The AVP will be used to extract the imposed expires from the 200ok reply.

This makes sense only in cached registrations scenario.

Default value is NULL.

#### Set `mcontact_avp` parameter

    ...
    modparam("registrar", "mcontact_avp", "$avp(register)")
    ...

### `attr_avp` (string)

AVP to store specific additional information for each registration. This information is read from the AVP and stored (in memory, db or both) at every registrar 'save'. When a registrar 'lookup' or 'is_registered' function is called, the attr_avp is populated with the value saved at [re]registration.

When doing call forking, the avp will hold multiple values. The position of the corresponding attribute information in attr_avp is equal to the branch index. An example scenario is given below.

Default value is NULL.

#### Set `attr_avp` parameter

    # reading attributes from the attr_pvar when doing parallel forking
    ...
    modparam("registrar", "attr_avp", "$avp(attr)")

    ...
    if (is_method("REGISTER")) {
    	$avp(attr) = "contact_info";
    	save("location");
    	exit;
    }
    ...
    lookup("location");
    t_on_branch("branch_route_1");
    ...
    branch_route[branch_route_1] {
    	xlog("Attributes for branch $T_branch_idx: $(avp(attr)[$T_branch_idx])\n");
    }

### `gruu_secret` (string)

The string that will be used in XORing when generating temporary GRUUs.

If not set, 'OpenSIPS' is the default secret.

#### Set `gruu_secret` parameter

    ...
    modparam("registrar", "gruu_secret", "top_secret")
    ...

### `disable_gruu` (int)

Globally disable GRUU handling

Default value is 1 ( GRUU will not be handled ).

#### Set `gruu_secret` parameter

    ...
    modparam("registrar", "disable_gruu", 0)
    ...

## Exported Functions

### `save(domain [,flags ,[aor]])`

The function processes a REGISTER message. It can add, remove or modify usrloc records depending on Contact and Expires HFs in the REGISTER message. On success, 200 OK will be returned listing all contacts that are currently in usrloc. On an error, error message will be send with a short description in reason phrase.

Meaning of the parameters is as follows:

- domain - Logical domain within registrar. If database is used then this must be name of the table which stores the contacts.

- flags (optional)- string of the following flags:

  - 'm' (Memory only) - save the contacts only in memory cache without no DB operation;

  - 'r' (no Reply) - do not generate a SIP reply to the current REGISTER request.

  - 's' (Socket header) - look into REGISTER request for a header which contains a socket description (proto:IP:port). This socket info will be stored by register instead of the received socket info.

  - 'cnn' (max Contacts) - this flag can be used to limit the number of contacts for this AOR (Address of Record) in the user location database. Value 0 disables the check. This parameter overrides the global "max_contacts" module parameter.

  - 'e(int)' (minimum expires) - this flag can be used to set minimum register expiration time. Values lower than this minimum will be automatically set to the minimum. Value 0 disables the checking. This parameter overrides the global "min_expires" module parameter.

  - 'E(int)' (maximum expires) - this flag can be used to set maximum register expiration time. Values higher than this maximum will be automatically set to the maximum. Value 0 disables the checking. This parameter overrides the global "max_expires" module parameter.

  - 'f' (force registration) - this flag can be used to force the registration of NEW contacts even if the maximum number of contacts is reached. In such a case, older contacts will be removed to make space to the new ones, without exceeding the maximum allowed number. This flag makes sense only if "cxx" is used.

  - 'p0' (Path support - 'off' mode) The Path header is saved into usrloc, but is never included in the reply.

  - 'p1' (Path support - lazy mode) The Path header is saved into usrloc, but is only included in the reply if path support is indicated in the registration request by the path option of the Supported header.

  - 'p2' (Path support - strict mode) The path header is only saved into usrloc, if path support is indicated in the registration request by the path option of the Supported header. If no path support is indicated, the request is rejected with 420 - Bad Extension and the header Unsupported: path is included in the reply along with the received Path header. This mode is the one recommended by RFC-3327.

  - 'v' (path receiVed) if set, the received parameter of the first Path URI of a registration is set as received-uri and the NAT branch flag is set for this contact. This is useful if the registrar is placed behind a SIP loadbalancer, which passes the nat'ed UAC address as received parameter in it's Path uri.

  This parameter is a string composed of a set of flags.

- aor (optional) - Variable contain a custom AOR; if missing, the AOR will be taken from the default place - the TO header URI.

This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.

#### `save` usage

    ...
    # save into 'location', no flags, use default AOR (TO URI)
    save("location");
    ...
    # save into 'location', do not update DB, max 5 contacts per AOR,
    # use default AOR (TO URI)
    save("location","mc5");
    ...
    # save into 'location', no flags, use as AOR the FROM URI
    save("location","","$fu");
    ...
    # save into 'location',no DB update, no reply to send, take AOR from AVP
    save("location","mr", "$avp(aor)");
    ...

### `remove(domain, AOR[, target])`

Explicitly remove contacts behind a given address-of-record.

Meaning of the parameters is as follows:

- domain - Logical domain within registrar. If database is used then this must be name of the table which stores the contacts.

- AOR - address-of-record to be searched (SIP URI)

- target (optional) - may be specified in two ways:

  - single delete - Specific contact to be deleted (SIP URI)

  - multi delete - IP/hostname of the AOR's contacts which will be deleted

This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.

#### `remove` usage

    ...
    # remove all contacts belonging to the "bob" AOR
    remove("location", "sip:bob@atlanta.com");
    ...
    # remove only bob's home phone
    remove("location", "sip:bob@atlanta.com", "sip:bob@46.50.64.78");
    ...
    # remove all bob's phones which are behind "50.60.50.60"
    $var(next_hop) = "50.60.50.60"
    remove("location", "sip:bob@atlanta.com", "$var(next_hop)");
    ...

### `lookup(domain [, flags [, aor]])`

The functions extracts username from Request-URI and tries to find all contacts for the username in usrloc. If there are no such contacts, -1 will be returned. If there are such contacts, Request-URI will be overwritten with the contact that has the highest q value and optionally the rest will be appended to the message (depending on append_branches parameter value).

If the method_filtering option is enabled, the lookup function will return only the contacts that support the method of the processed request.

Meaning of the parameters is as follows:

- domain - Name of table that should be used for the lookup.

- flags(optional)

  - 'b' (no Branches) - this flag controls how lookup function processes multiple contacts. If there are multiple contacts for the given username in usrloc and this flag is not set, Request-URI will be overwritten with the highest-q rated contact and the rest will be appended to sip_msg structure and can be later used by tm for forking. If the flag is set, only Request-URI will be overwritten with the highest-q rated contact and the rest will be left unprocessed.

  - 'r' (bRanch lookup) - this flag enables searching through existing branches for aor's and expanding them to contacts. For example, you have got AOR A in your ruri but you also want to forward your calls to AOR B. In order to do this, you must put AOR B in a branch, and if this flag enabled, the function will also expand AOR B to contacts, which will be put back into the branches. The AOR's that were in branches before the function call shall be removed.

    WARNING: if you want this flag activated, the 'b' (no Branches) flag must not be set, because by setting that flag you won't allow lookup to write in a branch.

  - 'm' (Method filtering) - this flag tells if the contact filtering based on supported methods should be performed during lookup.

  - 'u' (User-Agent filtering) - this flag enables regexp filtering by user-agent. It's useful with enabled append_branches parameter. Regexp must follow the 'u' flag and must use format like 'u/regexp/'.

  - 'i' (Case insensitive search) - this flag enables case insensitive filtering for the 'u' flag.

  - 'e' (Use extended regexp) - this flag enables using of extended regexp format for the 'u' flag.

- AOR (optional)- AOR to lookup for; if missing, the RURI is used as AOR; This must be a variable.

Return codes:

- 1 - contacts found and returned.

  -1 - no contact found.

  -2 - contacts found, but method not supported.

  -3 - internal error during processing.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

#### `lookup` usage

    ...
    lookup("location");  # simple lookup
       #or
    lookup("location","m"); # lookup with method filtering
       #or
    lookup("location","r"); #lookup with aor branch search;
    						#all contacts except the first one shall be put
    						#in the branches
       #or
    lookup("location","u/phone/i"); # lookup with user-agent filtering
       #or
    lookup("location","","$var(aor)"); # simple lookup with AOR from PV
    switch ($retcode) {
        case -1:
        case -3:
            sl_send_reply("404", "Not Found");
            exit;
        case -2:
            sl_send_reply("405", "Not Found");
            exit;
    };
    ...

### `registered(domain [,AOR[, callid]])`

The function returns true if an AOR is registered, false otherwise. The function does not modify the message being process.

NOTE: if called for a reply (from onreply_route), you must pass an AOR (as parameter), otherwise the function will fail.

Meaning of the parameters is as follows:

- domain - Name of table that should be used for the lookup.

- AOR (optional)- AOR to lookup for; if missing, the RURI is used as AOR; This must be a variable.

- callid (optional)- callid to check if a contact if registered with this callid (this may help you to make distinction between newly registered contact (callid not registered so far) and re-registration (callid already registered).

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.

WARNING: THIS FUNCTION IS DEPRECATED! USE is_registered() INSTEAD.

#### `registered` usage

    ...
    if (registered("location")) {
    	sl_send_reply("100", "Trying");
    	...
    };
    if (registered("location","$fu")) {
    	xlog("caller is registered\n");
    }
    ...

### `is_other_contact(domain , IPs)`

This function returns true if there are any other contacts registered, different from the ones from the IPs avp.

Meaning of the parameters is as follows:

- domain - Name of table that should be used for contacts lookup.

- IPs - an AVP containing the IP's that will be compared with the contacts from usrloc.

This function can be used from REQUEST_ROUTE.

WARNING: THIS FUNCTION IS DEPRECATED! USE is_ip_registered() INSTEAD.

#### `is_other_contact` usage

    ...

    if (is_other_contact("location", "$avp(ips)")) {
    	sl_send_reply("403", "Forbidden");
    	...
    };
    ...

### `is_registered(domain ,[AOR])`

The function returns true if an AOR is registered, false otherwise. The function does not modify the message being process.

Meaning of the parameters is as follows:

- domain - Name of table that should be used for the lookup.

- AOR (optional)- AOR to lookup for; if missing, the source if the AOR is the "To" header for REGISTER request, "From" header for any other sip request.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.

#### `is_registered` usage

    ...
    /**/
    if (is_method("REGISTER")) {
    	/* automatically uses the URI from the To header */
    	if (is_registered("location")) {
    		xlog("this AOR is registered\n")
    		...
    	}
    };
    /* check the From uri whether this aor is registered or not */
    if (is_registered("location","$fu")) {
    	xlog("caller is registered\n");
    }
    ...

### `is_contact_registered(domain ,[AOR],[contact],[callid])`

The function returns true if a contact and/or a callid from a certain AOR is registered, false otherwise. The function does not modify the message being process.

Meaning of the parameters is as follows:

- domain - Name of table that should be used for the lookup.

- AOR (optional)- AOR to lookup for; if missing, the source if the AOR is the "To" header for REGISTER request, "From" header for any other sip request.

- contact (optional)- callid to check if a contact if registered with this callid (this may help you to make distinction between newly registered contact (callid not registered so far) and re-registration (callid already registered).

- callid (optional)- callid to check if a contact if registered with this callid (this may help you to make distinction between newly registered contact (callid not registered so far) and re-registration (callid already registered).

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.

#### `is_contact_registered` usage

    ...
    /*let's say you want to block users that are not registered*/
    if (is_method("INVITE")) {
    	if (!is_contact_registered("location")) {
    		sl_send_reply("401", "Unauthorized");
    	...
    	}
    }
    /* you want to check the second contact from the message whether it is
    registered or not */
    if(is_method("INVITE")) {
    	if (is_contact_registered("location","$fu","$(ct[1])",))
    		xlog("caller is registered\n");
    }
    ...

### `is_ip_registered(domain ,[AOR],IPvar)`

The function returns true if at least a contact has an IP from the IPavp in it's received parameter,otherwise returns false. The function does not modify the message being process. This function replaces the "is_other_contact" function.

Meaning of the parameters is as follows:

- domain - Name of table that should be used for the lookup.

- AOR (optional)- AOR to lookup for; if missing, the source if the AOR is the "To" header for REGISTER request, "From" header for any other sip request.

- IPvar the pvar containing the IPs you want to check the received parameter of the contacts in the AOR against.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.

#### `is_ip_registered` usage

    ...
    /* check the source ip  whether it is already registered */
    if (is_method("REGISTER")) {
    	if (is_ip_registered("location","$tu","$si")) {
    		xlog("already registered from this ip\n");
    		...
    	}
    };
    ...

### `add_sock_hdr(hdr_name)`

Adds to the current REGISTER request a new header with hdr_name which contains the description of the received socket (proto:ip:port)

This makes sense only in multiple replicated servers scenarios.

Meaning of the parameters is as follows:

- hdr_name - header name to be used.

This function can be used from REQUEST_ROUTE.

#### `add_sock_hdr` usage

    ...
    add_sock_hdr("Sock-Info");
    ...

## Exported Statistics

### `max_expires`

Value of max_expires parameter.

### `max_contacts`

The value of max_contacts parameter.

### `defaults_expires`

The value of default_expires parameter.

### `accepted_regs`

Number of accepted registrations.

### `rejected_regs`

Number of rejected registrations.