;-- Geolocation Profile Sample Configuration --; ;-- ======================================================================= Overview ======================================================================= Geolocation information is actually comprised of two objects, a Location object, and a Profile object. Location objects must contain one of the following: - Location information specified in Geographic Markup Language (GML) or civicAddress formats. - A URI that points to externally hosted location information. Profile objects contain instructions for the disposition of location information, an optional reference to a Location object, and updates or overrides to that Location object if specified. Channel drivers and the dialplan functions are responsible for associating Profiles to endpoints/devices and calls. Normally, two profiles would be assigned to an endpoint to control behavior in each direction and to optionally specify location information. One for incoming calls (Asterisk is the UAS) and and one for outgoing calls (Asterisk is the UAC). NOTE: See https://wiki.asterisk.org/wiki/display/AST/Geolocation for the most complete and up-to-date information on valid values for the object parameters and a full list of references. GENERAL CAUTION: You must coordinate with your partners with regards to what location information is expected by each party and how it should be formatted. An outgoing configuration mismatch for instance, could result in misinformation or no information being sent to an emergency response center or even call failure for which you are solely responsible. --; ;-- ======================================================================= Location Object Description ======================================================================= [] -- type (required) ---------------------------------------------------- Defines the object type. type = location Must be "location" to identify this configuration section as a Geolocation Location object. -- format (required) -------------------------------------------------- Sets the format used to express the location. format = < civicAddress | GML | URI > Values: civicAddress: [RFC4119] [RFC5139] [RFC5491] The location information will be placed in an XML document conforming to the PIDF-LO standard. For chan_pjsip, this will be placed in the body of outgoing INVITE messages in addition to any SDP. GML: [RFC4119] [RFC5491] [GeoShape] The location information will be placed in an XML document conforming to the PIDF-LO standard. For chan_pjsip, this will be placed in the body of outgoing INVITE messages in addition to any SDP. URI: [RFC6442] The external URI at which the the location information can be found. For chan_pjsip, this URI will be placed in a "Geolocation" header in outgoing INVITE messages. There is no default. Example: format = civicAddress -- location_info (required) ------------------------------------------- The location-format-specific information describing the location. location_info = For readability, multiple "location" parameters can be specified and they will be concatenated into one specification. The description may contain replacement variables which may be the names of common channel variables like ${EXTEN}, channel variables you may have added in the dialplan, or variables you may have specified in the profile that references this location object. NOTE: See https://wiki.asterisk.org/wiki/display/AST/Geolocation for the most complete and up-to-date information on valid values for the object parameters and a full list of references. WARNING: Asterisk can only validate that a particular sub-parameter name is valid for a particular format. It can't validate the actual value of the sub-parameter. Example for civicAddress: location_info = country=US location_info = A1="New York", A3="New York", A4=Manhattan, location_info = HNO=1633, PRD=W, RD=46th, STS=Street location_info = PC=10222 Example for GML with replacement variables: location_info = type=Point, crs=2d, pos="${mylat} ${mylon}" Example for URI with replacement variables: location_info = URI=https://some.company.com?number=${phone_number} -- method (optional) -------------------------------------------------- The method used to determine the location_info method = <"GPS" | "A-GPS" | "Manual" | "DHCP" | "Triangulation" | "Cell" | "802.11"> Example: method = Manual -- location_source (optional) ----------------------------------------- Original source of the location-info. location_source = < FQDN > The value MUST be a FQDN. IP addresses are specifically not allowed. See RFC8787. Example: location_source = sip1.myserver.net -- confidence (optional) ----------------------------------------- The confidence in the location specified. confidence = pdf=[ unknown | normal | rectangular ], value= Please see RFC7459 for the exact description of this parameter. Example: confidence = pdf=normal, value=75 -- Location Example --------------------------------------------------- [mylocation] type = location format = civicAddress location_info = country=US location_info = A1="New York", A3="New York", A4=Manhattan location_info = HNO=1633, PRD=W, RD=46th, STS=Street location_info = PC=10222 method = Manual location_source = sip1.myserver.net ======================================================================= --; ;-- ======================================================================= Profile Object Descriptions ======================================================================= [] -- type (required) ---------------------------------------------------- Defines the object type. type = profile -- profile_precedence (optional) -------------------------------------- Sets how to reconcile incoming and configured profiles. profile_precedence = < prefer_incoming | prefer_config | discard_incoming | discard_config > On an incoming call leg, "incoming" is the location description received in the SIP INVITE (if any) and "config" is this profile. On an outgoing call leg, "incoming" is the location description passed through the dialplan to this channel (if any) and "config" is this profile. Values: prefer_incoming: If there's an incoming location description, use it even if there's also a configured one. prefer_config: If there's a configured location description, use it even if there's also an incoming one. discard_incoming: Discard any incoming location description. If there's a configured one, use it. If not, no location information is propagated. discard_config: Discard any configured location description. If there's an incoming one, use it. If not, no location information is propagated. discard_incoming is the default. Example: profile_precedence = prefer_config -- pidf_element (optional) -------------------------------------------- PIDF-LO element in which to place the location description. pidf_element = < tuple | device | person > Default: device If the format is civicAddress or GML, this sets the PIDF element into which the location information will be placed. Values: tuple: Places the information in a "tuple" element. device: Places the information in a "device" element. person: Places the information in a "person" element. Per [RFC5491], "device" is preferred and therefore the default. Example: pidf_element = tuple -- allow_routing_use (optional) --------------------------------------- Sets whether the "Geolocation-Routing" header is added to outgoing requests. allow_routing_use = < yes | no > Default: no Set to "yes" to indicate that servers later in the path can use the location information for routing purposes. Set to "no" if they should not. If this value isn't specified, no "Geolocation-Routing" header will be added. Example: allow_routing_use = yes -- location_reference (optional) -------------------------------------- The name of an existing Location object. location_reference = The location_info_refinement and location_variables parameters below can be used to refine the location object for this specific profile. Example: location_reference = "my_building" -- location_info_refinement (optional) -------------------------------- Location info to add to that already retrieved from the location object. location_info_refinement = The information in the referenced Location object can be refined on a per-profile basis. For example, if the referenced Location object has a civicAddress for a building, you could set location_refinement to add a floor and room just for this profile Example: location_info_refinement = floor=20, room=20a2 -- location_variables (optional) -------------------------------------- If the referenced Location object uses any replacement variables, they can be assigned here. There is no need to define variables that come from the channel using this profile. They get assigned automatically. location_variables = myfloor=20, myroom=222 -- suppress_empty_ca_elements (optional) ------------------------------ Sets whether empty values for Civic Address elements should be suppressed from the outgoing PIDF-LO document. suppress_empty_ca_elements = < yes | no > Default: no Setting to "yes" allows you to define a location info template with channel variables that may or may not exist. For example, with: location_info_refinement = FLR=${MyFlr} suppress_empty_ca_elements = no ; the default If the MyFlr channel variable weren't set, the outgoing PIDF-LO document would have an empty element in it. If suppress_empty_ca_elements were set to "yes", the FLR element would be dropped from the PIDF-LO document altogether. -- format, location_info, location_source, method, confidence --------- You can specify the location object's format, location_info, method, location_source and confidence parameters directly on a profile object for simple scenarios where the location information isn't common with any other profiles. This is mutually exclusive with setting location_reference on the profile. -- Profile Example ---------------------------------------------------- [myprofile] type = profile location_reference = mylocation location_info_refinement = floor=20, room=20a2 pidf_element = tuple profile_action = discard_incoming ======================================================================= --; -- NOTE --------------------------------------------------------------- There are 4 built-in profiles that can be assigned to endpoints: "" "" "" "" The profiles are empty except for having their precedence set.