Ticket #1412 (closed enhancement: fixed)

Opened 5 years ago

Last modified 5 years ago

Account specific NAT settings: STUN, ICE, and TURN

Reported by: bennylp Owned by: bennylp
Priority: normal Milestone: release-2.1
Component: pjsua-lib Version: trunk
Keywords: Cc:
Backport to 1.x milestone: Backported: no

Description (last modified by bennylp) (diff)

With #539 it is now possible to configure STUN, ICE, and TURN settings on per account basis. This is needed for example when application is supporting multiple accounts where one is connecting through Internet and the other is through VPN. The specification is as follows.

Enable/disable STUN per account

The STUN server settings are still in the global pjsua_config. New settings are introduced in the account config to disable or enable STUN for either SIP or media transports: sip_stun_use and media_stun_use:

/**
 * This enumeration controls the use of STUN in the account.
 */
typedef enum pjsua_stun_use
{
    /**
     * Follow the default setting in the global \a pjsua_config.
     */
    PJSUA_STUN_USE_DEFAULT,

    /**
     * Disable STUN. If STUN is not enabled in the global \a pjsua_config,
     * this setting has no effect.
     */
    PJSUA_STUN_USE_DISABLED

} pjsua_stun_use;

struct pjsua_acc_config
{
    ...

    /**
     * Control the use of STUN for the SIP signaling.
     *
     * Default: PJSUA_STUN_USE_DEFAULT
     */
    pjsua_stun_use 		sip_stun_use;

    /**
     * Control the use of STUN for the media transports.
     *
     * Default: PJSUA_STUN_USE_DEFAULT
     */
    pjsua_stun_use 		media_stun_use;

    ...
};

ICE and TURN settings per account

New ICE and TURN configurations in the account config to override the global config in the pjsua_media_config:

/**
 * This enumeration controls the use of ICE settings in the account.
 */
typedef enum pjsua_ice_config_use
{
    /**
     * Use the default settings in the global \a pjsua_media_config.
     */
    PJSUA_ICE_CONFIG_USE_DEFAULT,

    /**
     * Use the custom \a pjsua_ice_config setting in the account.
     */
    PJSUA_ICE_CONFIG_USE_CUSTOM

} pjsua_ice_config_use;

/**
 * This enumeration controls the use of TURN settings in the account.
 */
typedef enum pjsua_turn_config_use
{
    /**
     * Use the default setting in the global \a pjsua_media_config.
     */
    PJSUA_TURN_CONFIG_USE_DEFAULT,

    /**
     * Use the custom \a pjsua_turn_config setting in the account.
     */
    PJSUA_TURN_CONFIG_USE_CUSTOM

} pjsua_turn_config_use;

/**
 * ICE setting. This setting is used in the pjsua_acc_config.
 */
typedef struct pjsua_ice_config
{
    /**
     * Enable ICE.
     */
    pj_bool_t		enable_ice;

    /**
     * Set the maximum number of host candidates.
     *
     * Default: -1 (maximum not set)
     */
    int			ice_max_host_cands;

    /**
     * ICE session options.
     */
    pj_ice_sess_options	ice_opt;

    /**
     * Disable RTCP component.
     *
     * Default: no
     */
    pj_bool_t		ice_no_rtcp;

} pjsua_ice_config;

/**
 * TURN setting. This setting is used in the pjsua_acc_config.
 */
typedef struct pjsua_turn_config
{
    /**
     * Enable TURN candidate in ICE.
     */
    pj_bool_t		enable_turn;

    /**
     * Specify TURN domain name or host name, in in "DOMAIN:PORT" or
     * "HOST:PORT" format.
     */
    pj_str_t		turn_server;

    /**
     * Specify the connection type to be used to the TURN server. Valid
     * values are PJ_TURN_TP_UDP or PJ_TURN_TP_TCP.
     *
     * Default: PJ_TURN_TP_UDP
     */
    pj_turn_tp_type	turn_conn_type;

    /**
     * Specify the credential to authenticate with the TURN server.
     */
    pj_stun_auth_cred	turn_auth_cred;

} pjsua_turn_config;

struct pjsua_acc_config
{
    ...

    /**
     * Control the use of ICE in the account. By default, the settings in the
     * \a pjsua_media_config will be used.
     *
     * Default: PJSUA_ICE_CONFIG_USE_DEFAULT
     */
    pjsua_ice_config_use	ice_cfg_use;

    /**
     * The custom ICE setting for this account. This setting will only be
     * used if \a ice_cfg_use is set to PJSUA_ICE_CONFIG_USE_CUSTOM
     */
    pjsua_ice_config		ice_cfg;

    /**
     * Control the use of TURN in the account. By default, the settings in the
     * \a pjsua_media_config will be used
     *
     * Default: PJSUA_TURN_CONFIG_USE_DEFAULT
     */
    pjsua_turn_config_use	turn_cfg_use;

    /**
     * The custom TURN setting for this account. This setting will only be
     * used if \a turn_cfg_use is set to PJSUA_TURN_CONFIG_USE_CUSTOM
     */
    pjsua_turn_config		turn_cfg;

    ...
};

Contact header generation

The initial value of Contact header will take into account whether STUN is enabled or disabled in the account. If it is disabled, local IP will be used. More over, for UDP transport, if STUN is not used or disabled for the account, an attempt will be made to use the correct IP interface to be placed in the Contact URI.

No change for TCP; the correct IP has already been selected in the Contact URI.

Subsequent update to the Contact header doesn't change.

Via sent-by generation

Initial Via sent-by value now will be affected by STUN setting in the account. If it is disabled, local IP will be used. More over, for UDP transport, if STUN is not used or disabled for the account, an attempt will be made to use the correct IP interface to be placed in the Contact URI.

No change for TCP; the correct IP has already been displayed in the Via sent-by.

Subsequent update of the value doesn't change; it follows the rules in #1537.

Media transports

STUN, ICE, and TURN setup of the media transports now will follow the account config settings instead.

pjsua

New option --disable-stun is added.

Change History

comment:1 Changed 5 years ago by bennylp

  • Type changed from defect to enhancement
  • Backported unset

comment:2 Changed 5 years ago by bennylp

  • Description modified (diff)
  • Milestone changed from release-2.x to release-2.1

comment:3 Changed 5 years ago by bennylp

  • Summary changed from Add media transport preferences (STUN, ICE settings) to account setting (thanks Régis Montoya for the suggestion) to Add transport preferences (STUN, ICE settings) to account setting (thanks Régis Montoya for the suggestion)

comment:4 Changed 5 years ago by bennylp

  • Description modified (diff)

comment:5 Changed 5 years ago by bennylp

  • Description modified (diff)

comment:6 Changed 5 years ago by bennylp

  • Description modified (diff)
  • Summary changed from Add transport preferences (STUN, ICE settings) to account setting (thanks Régis Montoya for the suggestion) to Account specific NAT settings: STUN, ICE, and TURN

comment:7 Changed 5 years ago by bennylp

  • Description modified (diff)

comment:8 Changed 5 years ago by bennylp

  • Description modified (diff)

comment:9 Changed 5 years ago by bennylp

  • Description modified (diff)

comment:10 Changed 5 years ago by bennylp

  • Description modified (diff)

comment:11 Changed 5 years ago by bennylp

  • Status changed from new to closed
  • Resolution set to fixed

In 4218:

Fixed #1412: Account specific NAT settings: STUN, ICE, and TURN

comment:12 Changed 5 years ago by bennylp

In 4227:

More re #1412: set default value of PJSIP_CHECK_VIA_SENT_BY to 0, because now account may send requests with different Via sent-by

comment:13 Changed 5 years ago by bennylp

In r4229:

Also handle the case for presence subscription, publish, and mwi when the account does not have registration.

Note: See TracTickets for help on using tickets.