From: Kinsey Moore Date: Sun, 19 May 2013 17:45:42 +0000 (+0000) Subject: Add base XML documentation for res_sip X-Git-Tag: 13.0.0-beta1~1795 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1b5a3069f97661e4f00e56904d8bc546370c41b0;p=thirdparty%2Fasterisk.git Add base XML documentation for res_sip Thanks to Brad Latus, this patch adds a significant amount much-needed documentation to res_sip. It should cover all existing configuration options currently in Asterisk trunk. Patch-by: Brad Latus (snuffy) Review: https://reviewboard.asterisk.org/r/2471/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@389148 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- diff --git a/res/res_sip.c b/res/res_sip.c index ac2e9279b5..7f6b061c90 100644 --- a/res/res_sip.c +++ b/res/res_sip.c @@ -42,6 +42,512 @@ core ***/ +/*** DOCUMENTATION + + SIP Resource using PJProject + + + Endpoint + + The Endpoint is the primary configuration object. + It contains the core SIP related options only, endpoints are NOT + dialable entries of their own. Communication with another SIP device is + accomplished via Addresses of Record (AoRs) which have one or more + contacts assicated with them. Endpoints NOT configured to + use a transport will default to first transport found + in res_sip.conf that matches its type. + + Example: An Endpoint has been configured with no transport. + When it comes time to call an AoR, PJSIP will find the + first transport that matches the type. A SIP URI of sip:5000@[11::33] + will use the first IPv6 transport and try to send the request. + + + + Allow support for RFC3262 provisional ACK tags + + + + + + + + + + + When enabled, aggregate_mwi condenses message + waiting notifications from multiple mailboxes into a single NOTIFY. If it is disabled, + individual NOTIFYs are sent for each mailbox. + + + Media Codec(s) to allow + + + AoR(s) to be used with the endpoint + + List of comma separated AoRs that the endpoint should be associated with. + + + + Authentication Object(s) associated with the endpoint + + This is a comma-delimited list of auth sections defined + in res_sip.conf to be used to verify inbound connection attempts. + + Endpoints without an authentication object + configured will allow connections without vertification. + + + + CallerID information for the endpoint + + Must be in the format Name <Number>, + or only <Number>. + + + + Default privacy level + + + + + + + + + + + + + + + + Internal id_tag for the endpoint + + + Dialplan context for inbound sessions + + + Mitigation of direct media (re)INVITE glare + + + This setting attempts to avoid creating INVITE glare scenarios + by disabling direct media reINVITEs in one direction thereby allowing + designated servers (according to this option) to initiate direct + media reINVITEs without contention and significantly reducing call + setup time. + + + A more detailed description of how this option functions can be found on + the Asterisk wiki https://wiki.asterisk.org/wiki/display/AST/SIP+Direct+Media+Reinvite+Glare+Avoidance + + + + + + + + + + Direct Media method type + + Method for setting up Direct Media between endpoints. + + + + Alias for the invite value. + + + + + + + Determines whether media may flow directly between endpoints. + + + Disable direct media session refreshes when NAT obstructs the media session + + + Media Codec(s) to disallow + + + DTMF mode + + This setting allows to choose the DTMF mode for endpoint communication. + + + DTMF is sent out of band of the main audio stream.This + supercedes the older RFC-2833 used within + the older chan_sip. + + + DTMF is sent as part of audio stream. + + + DTMF is sent as SIP INFO packets. + + + + + + IP used for External Media handling + + + Force use of return port + + + Enable the ICE mechanism to help traverse NAT + + + Way(s) for Endpoint to be identified + + There are currently two methods to identify an endpoint. By default + both are used to identify an endpoint. + + + + + + + + + + Mailbox(es) to be associated with + + + Default Music On Hold class + + + Authentication object used for outbound requests + + + Proxy through which to send requests + + + Interval at which to qualify an endpoint + + Interval between attempts to qualify the endpoint for reachability. + If 0 never qualify. Time in seconds. + + + + Allow Contact header to be rewritten with the source IP address-port + + + Allow use of IPv6 for RTP traffic + + + Enforce that RTP must be symmetric + + + Send the P-Asserted-Identity header + + + Send the Remote-Party-ID header + + + Minimum session timers expiration period + + Minimium session timer expiration period. Time in seconds. + + + + Session timers for SIP packets + + + + + + + + + + + Maximum session timer expiration period + + Maximium session timer expiration period. Time in seconds. + + + + Desired transport configuration + + This will set the desired transport configuration to send SIP data through. + + Not specifying a transport will DEFAULT + to the first configured transport in res_sip.conf which is + valid for the URI we are trying to contact. + + + + + Trust inbound CallerID information from endpoint + This option determines whether res_sip will accept identification from the endpoint + received in a P-Asserted-Identity or Remote-Party-ID header. If no, + the configured Caller-ID from res_sip.conf will always be used as the identity for the + endpoint. + + + Trust endpoint with private CallerID information + This option determines whether res_sip will send identification + information to the endpoint that has been marked as private. If no, + private Caller-ID information will not be forwarded to the endpoint. + + + Must be of type 'endpoint'. + + + Use Endpoint's requested packetisation interval + + + + Authentication type + + Authentication objects hold the authenitcation information for use + by endpoints. This also allows for multiple + endpoints to use the same information. Choice of MD5/plaintext + and setting of username. + + + Authentication type + + This option specifies which of the password style config options should be read, + either 'password' or 'md5_cred' when trying to authenticate an endpoint inbound request. + + + + + + + + + Lifetime of a nonce associated with this authentication config. + + + MD5 Hash used for authentication. + Only used when auth_type is md5. + + + PlainText password used for authentication. + Only used when auth_type is userpass. + + + SIP realm for endpoint + + + Must be 'auth' + + + Username to use for account + + + + XXX This exists only to prevent XML documentation errors. + + I should be undocumented or hidden + + + I should be undocumented or hidden + + + + Domain Alias + + Signifies that a domain is an alias. Used for checking the domain of + the AoR to which the endpoint is binding. + + + Must be of type 'domain_alias'. + + + Domain to be aliased + + + + SIP Transport + + Transports + + There are different transports and protocol derivatives + supported by res_sip. They are in order of + preference: UDP, TCP, and WebSocket (WS). + + Multiple endpoints using the same connection is NOT + supported. Doing so may result in broken calls. + + + + Number of simultaneous Asynchronous Operations + + + IP Address and optional port to bind to for this transport + + + File containing a list of certificates to read (TLS ONLY) + + + Certificate file for endpoint (TLS ONLY) + + + Preferred Cryptography Cipher (TLS ONLY) + + Many options for acceptable ciphers see link for more: + http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS + + + + Domain the transport comes from + + + External Address to use in RTP handling + + + External address for SIP signalling + + + External port for SIP signalling + + + Method of SSL transport (TLS ONLY) + + + + + + + + + + + + + Network to consider local (used for NAT purposes). + This must be in CIDR or dotted decimal format with the IP + and mask separated with a slash ('/'). + + + Password required for transport + + + Private key file (TLS ONLY) + + + Protocol to use for SIP traffic + + + + + + + + + + Require client certificate (TLS ONLY) + + + Must be of type 'transport'. + + + Require verification of client certificate (TLS ONLY) + + + Require verification of server certificate (TLS ONLY) + + + + A way of creating an aliased name to a SIP URI + + Contacts are a way to hide SIP URIs from the dialplan directly. + They are also used to make a group of contactable parties when + in use with AoR lists. + + + Must be of type 'contact'. + + + SIP URI to contact peer + + + Time to keep alive a contact + + Time to keep alive a contact. String style specification. + + + + + The configuration for a location of an endpoint + + An AoR is what allows Asterisk to contact an endpoint via res_sip. If no + AoRs are specified, an endpoint will not be reachable by Asterisk. + Beyond that, an AoR has other uses within Asterisk. + + An AoR is a way to allow dialing a group + of Contacts that all use the same + endpoint for calls. + + This can be used as another way of grouping a list of contacts to dial + rather than specifing them each directly when dialing via the dialplan. + This must be used in conjuction with the PJSIP_DIAL_CONTACTS. + + + Permanent contacts assigned to AoR + + Contacts included in this list will be called whenever referenced + by chan_pjsip. + + + + Default expiration time in seconds for contacts that are dynamically bound to an AoR. + + + Mailbox(es) to be associated with + This option applies when an external entity subscribes to an AoR + for message waiting indications. The mailboxes specified here will be + subscribed to. + + + Maximum time to keep an AoR + + Maximium time to keep a peer with explicit expiration. Time in seconds. + + + + Maximum number of contacts that can bind to an AoR + + Maximum number of contacts that can associate with this AoR. + + This should be set to 1 and + remove_existing set to yes if you + wish to stick with the older chan_sip behaviour. + + + + + Minimum keep alive time for an AoR + + Minimum time to keep a peer with an explict expiration. Time in seconds. + + + + Determines whether new contacts replace existing ones. + + On receiving a new registration to the AoR should it remove + the existing contact that was registered against it? + + This should be set to yes and + max_contacts set to 1 if you + wish to stick with the older chan_sip behaviour. + + + + + Must be of type 'aor'. + + + + + ***/ + + static pjsip_endpoint *ast_pjsip_endpoint; static struct ast_threadpool *sip_threadpool; diff --git a/res/res_sip_acl.c b/res/res_sip_acl.c index 07e4d76e5e..f626a976fc 100644 --- a/res/res_sip_acl.c +++ b/res/res_sip_acl.c @@ -32,6 +32,58 @@ #include "asterisk/sorcery.h" #include "asterisk/acl.h" +/*** DOCUMENTATION + + SIP ACL module + + ACL + + The ACL module used by res_sip. This module is + independent of endpoints and operates on all inbound + SIP communication using res_sip. + + It should be noted that this module can also reference ACLs from + acl.conf. + + There are two main ways of creating an access list: IP-Domain + and Contact Header. It is possible to create a combined ACL using + both IP and Contact. + + + + Access Control List + + Name of IP ACL + + This matches sections configured in acl.conf + + + + Name of Contact ACL + + This matches sections configured in acl.conf + + + + List of Contact Header addresses to Deny + + + List of Contact Header addresses to Permit + + + List of IP-domains to deny access from + + + List of IP-domains to allow access from + + + Must be of type 'acl'. + + + + + ***/ + struct sip_acl { SORCERY_OBJECT(details); struct ast_acl_list *acl; diff --git a/res/res_sip_endpoint_identifier_ip.c b/res/res_sip_endpoint_identifier_ip.c index e3630ad072..89bf1d5543 100644 --- a/res/res_sip_endpoint_identifier_ip.c +++ b/res/res_sip_endpoint_identifier_ip.c @@ -30,6 +30,25 @@ #include "asterisk/module.h" #include "asterisk/acl.h" +/*** DOCUMENTATION + + Module that identifies endpoints via source IP address + + + + Name of Endpoint + + + IP addresses or networks to match against + + + Must be of type 'identify'. + + + + + ***/ + /*! \brief Structure for an IP identification matching object */ struct ip_identify_match { /*! \brief Sorcery object details */ diff --git a/res/res_sip_outbound_registration.c b/res/res_sip_outbound_registration.c index f33370146e..9d73f37d55 100644 --- a/res/res_sip_outbound_registration.c +++ b/res/res_sip_outbound_registration.c @@ -31,6 +31,67 @@ #include "asterisk/module.h" #include "asterisk/taskprocessor.h" +/*** DOCUMENTATION + + SIP resource for outbound registrations + + Outbound Registration + + This module allows res_sip to register to other SIP servers. + + + + The configuration for outbound registration + + Registration is COMPLETELY separate from the rest of + res_sip.conf. A minimal configuration consists of + setting a server_uri and a client_uri. + + + Determines whether failed authentication challenges are treated + as permanent failures. + If this option is enabled and an authentication challenge fails, + registration will not be attempted again until the configuration is reloaded. + + + Client SIP URI used when attemping outbound registration + + + Contact User to use in request + + + Expiration time for registrations in seconds + + + Maximum number of registration attempts. + + + Authentication object to be used for outbound registrations. + + + Outbound Proxy used to send registrations + + + Interval in seconds between retries if outbound registration is unsuccessful + + + SIP URI of the server to register against + + + Transport used for outbound authentication + + A transport configured in + res_sip.conf. As with other res_sip modules, this will use the first available transport of the appropriate type if unconfigured. + + + + Must be of type 'registration'. + + + + + ***/ + /*! \brief Amount of buffer time (in seconds) before expiration that we re-register at */ #define REREGISTER_BUFFER_TIME 10