kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2026-04-23 15:17:10 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
23
asterisk/configs/samples/geolocation.conf.sample
George Joseph 0a7a20b7fa res_geolocation: Fix multiple issues with XML generation. 
* 3d positions were being rendered without an enclosing `<gml:pos>`
  element resulting in invalid XML.
* There was no way to set the `id` attribute on the enclosing `tuple`, `device`
  and `person` elements.
* There was no way to set the value of the `deviceID` element.
* Parsing of degree and radian UOMs was broken resulting in them appearing
  outside an XML element.
* The UOM schemas for degrees and radians were reversed.
* The Ellipsoid shape was missing and the Ellipse shape was defined multiple
  times.
* The `crs` location_info parameter, although documented, didn't work.
* The `pos3d` location_info parameter appears in some documentation but
  wasn't being parsed correctly.
* The retransmission-allowed and retention-expiry sub-elements of usage-rules
  were using the `gp` namespace instead of the `gbp` namespace.

In addition to fixing the above, several other code refactorings were
performed and the unit test enhanced to include a round trip
XML -> eprofile -> XML validation.

Resolves: #1667

UserNote: Geolocation: Two new optional profile parameters have been added.
* `pidf_element_id` which sets the value of the `id` attribute on the top-level
  PIDF-LO `device`, `person` or `tuple` elements.
* `device_id` which sets the content of the `<deviceID>` element.
Both parameters can include channel variables.

UpgradeNote: Geolocation: In order to correct bugs in both code and
documentation, the following changes to the parameters for GML geolocation
locations are now in effect:
* The documented but unimplemented `crs` (coordinate reference system) element
  has been added to the location_info parameter that indicates whether the `2d`
  or `3d` reference system is to be used. If the crs isn't valid for the shape
  specified, an error will be generated. The default depends on the shape
  specified.
* The Circle, Ellipse and ArcBand shapes MUST use a `2d` crs.  If crs isn't
  specified, it will default to `2d` for these shapes.
  The Sphere, Ellipsoid and Prism shapes MUST use a `3d` crs. If crs isn't
  specified, it will default to `3d` for these shapes.
  The Point and Polygon shapes may use either crs.  The default crs is `2d`
  however so if `3d` positions are used, the crs must be explicitly set to `3d`.
* The `geoloc show gml_shape_defs` CLI command has been updated to show which
  coordinate reference systems are valid for each shape.
* The `pos3d` element has been removed in favor of allowing the `pos` element
  to include altitude if the crs is `3d`.  The number of values in the `pos`
  element MUST be 2 if the crs is `2d` and 3 if the crs is `3d`.  An error
  will be generated for any other combination.
* The angle unit-of-measure for shapes that use angles should now be included
  in the respective parameter.  The default is `degrees`. There were some
  inconsistent references to `orientation_uom` in some documentation but that
  parameter never worked and is now removed.  See examples below.
Examples...
```
  location_info = shape="Sphere", pos="39.0 -105.0 1620", radius="20"
  location_info = shape="Point", crs="3d", pos="39.0 -105.0 1620"
  location_info = shape="Point", pos="39.0 -105.0"
  location_info = shape=Ellipsoid, pos="39.0 -105.0 1620", semiMajorAxis="20"
                semiMinorAxis="10", verticalAxis="0", orientation="25 degrees"
  pidf_element_id = ${CHANNEL(name)}-${EXTEN}
  device_id = mac:001122334455
  Set(GEOLOC_PROFILE(pidf_element_id)=${CHANNEL(name)}/${EXTEN})
```
2026-01-05 12:45:05 +00:00

341 lines
12 KiB
Plaintext
Raw Permalink Blame History

;--
Geolocation Profile Sample Configuration
Please see https://docs.asterisk.org/Deployment/Geolocation/
for the most current information.
--;
;--
=======================================================================
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://docs.asterisk.org/Deployment/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
=======================================================================
[<location_id>]
-- 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] [RFC4479] [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 = <location_format_specific_description>
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://docs.asterisk.org/Deployment/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=<percent_confident>
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
=======================================================================
[<profile_id>]
-- 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
-- pidf_element id(optional) ------------------------------------------
Sets the value of the 'id' attribute for the top-level PIDF-LO element.
You can reference channel variables in this parameter.
pidf_element_id = <any valid attribute string>
Example:
pidf_element_id = ${CHANNEL(name)}
-- device_id (optional) -----------------------------------------------
Sets the contents of the <dm:deviceID> element in the top-level
PIDF-LO element. RFC4479 defined this only as a 'URN' with the only
examples being a mac address in the format 'mac:XXXXXXXXXXXX'.
You can reference channel variables in this parameter.
device_id = <urn>
Example:
device_id = mac:40000b0c0d12
device_id = mac:${MAC_ADDRESS}
-- 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 = <location_id>
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 = <location_format_specific_description>
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 <FLR/> 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:
"<prefer_config>"
"<discard_config>"
"<prefer_incoming>"
"<discard_incoming>"
The profiles are empty except for having their precedence
set.
--;
Reference in New Issue View Git Blame Copy Permalink