Configuration File

Most of the Traccar server configuration parameters are located in a single text file (traccar.xml). On Linux and Mac platforms the path to the file is /opt/traccar/conf/; on Windows the path can be changed during the installation process, but by default it should be in C:\Program Files\Traccar\conf. Configuration file can be edited using any text editor.

Some of the parameters are configured via attributes on Device, Server and other objects through web interface. Check badge next to the attribute key for information on where particular parameter can be used.

For boolean (true/false) values, if the value is not specified then server treats it as false.

List of available configuration parameters:

config.default config

Path to the default config file.

web.enable config

Flag to enable or disable Traccar web interface (true to enable, false to disable).

web.address config

Optional parameter to specify network interface for web interface to bind to. By default server will bind to all available interfaces.

web.port config

Web interface TCP port number. By default Traccar uses port 8082. To avoid specifying port in the browser you can set it to 80 (default HTTP port).

web.path config

Path to the directory that contains web interface files.

web.debug config

Boolean flag to use non-minified (debug) version of the web interface. If false it uses release.html file by default, if true it uses debug.html by default. Default value is false.

web.console config

Flag to enable database console. It is recommended to use on local development environment because it exposes raw database access via web interface. If enabled, console is available under "/console" URL path.

web.timeout config

WebSocket timeout value in milliseconds. Default value is 1 minute.

web.old config

Flag to enable or disable old Traccar web interface (true to enable, false to disable).

web.application config

Full path to the old version of the web interface WAR file. Set this only if you plan to use old web interface.

geocoder.enable config

Boolean flag to enable or disable reverse geocoder.

geocoder.type config

Reverse geocoder type. Currently Traccar support following types: google, nominatim and gisgraphy. By default (if the value is not specified) server uses Google API.

geocoder.url config

Geocoder server URL. Applicable only to Nominatim and Gisgraphy geocoders.

geocoder.processInvalidPositions config

Boolean flag to apply reverse geocoding to invalid positions.

geocoder.format config

Address format string. Default value is %h %r, %t, %s, %c. Possible options:

  • %p - postcode
  • %c - country
  • %s - state
  • %d - district
  • %t - settlement (town)
  • %u - suburb
  • %r - street (road)
  • %h - house
geocoder.reuseDistance config

Optional parameter to specify minimum distance for new reverse geocoding request. If distance is less than specified value (in meters), then Traccar will reuse last known address.

geolocation.enable config

Boolean flag to enable LBS location resolution. Some devices send cell towers information and WiFi point when GPS location is not available. Traccar can determine coordinates based on that information using third party services. Default value is false.

geolocation.type config

Provider to use for LBS location. Available options: mozilla and opencellid. By default opencellid is used.

geolocation.key config

Provider API key. OpenCellID service requires API key.

geolocation.mcc config

Some devices don't report MCC value, so this parameter can be used to provide it.

geolocation.mnc config

Some devices don't report MNC value, so this parameter can be used to provide it.

geolocation.processInvalidPositions config

Boolean flag to apply geolocation to invalid positions.

filter.enable config

Boolean flag to enable or disable position filtering.

filter.limit config

Time limit for the filtering in seconds. If the time difference between last position and a new one is more than this limit, the new position will not be filtered out.

filter.invalid config

Filter invalid (valid field is set to false) positions.

filter.zero config

Filter zero coordinates. Zero latitude and longitude are theoretically valid values, but it practice it usually indicates invalid GPS data.

filter.duplicate config

Filter duplicate records (duplicates are detected by time value).

filter.distance config

Filter records by distance. The values is specified in meters. If the new position is less far than this value from the last one it gets filtered out.

filter.future config

Filter records with fix time in future. The values is specified in seconds. Records that have fix time more than specified number of seconds later than current server time would be filtered out.

filter.maxSpeed config

Filter records by Maximum Speed, value in knots. Can be used to filter jumps to far locations even if they're marked as valid. Shouldn't be to low unless you know what you do, start testing with values at about 25000.

distance.enable config

Calculate and accumulate travelled distance for all devices. Distance value is in meters and is stored in the position attributes.

logger.enable config

Boolean flag to enable or disable logging. Log file contains useful information for investigating problems with Traccar server.

logger.level config

Minimum severity of the events to put into the log file. By default the values is 'all' which enables logging of all messages.

logger.file config

Full path to the log file.

processing.remoteAddress.enable config

Enable to save device IP addresses information. Disabled by default.

processing.copyAttributes.enable config

Enable copying of missing attributes from last position to the current one. Might be useful if device doesn't send some values in every message.

processing.copyAttributes config

List of attributes to copy if missing. Attribute names should be separated by a comma. For example "power,ignition,battery".

database.driverFile config

Path to the database driver JAR file. Traccar includes drivers for MySQL, PostgreSQL and H2 databases. If you use one of those, you don't need to specify this parameter.

database.driver config

Database driver Java class. For H2 use 'org.h2.Driver'. MySQL driver class name is 'com.mysql.jdbc.Driver'.

database.url config

Database connection URL. By default Traccar uses H2 database. For MySQL URL syntax see this page.

database.user config

Database user name. Default administrator user for H2 database is 'sa'.

database.password config

Database user password. Default password for H2 admin (sa) user is empty.

database.changelog config

Path to Liquibase master changelog file.

database.checkConnection config

SQL query to check connection status. Default value is 'SELECT 1'. For Oracle database you can use 'SELECT 1 FROM DUAL'.

database.ignoreUnknown config

Boolean flag to ignore unknown devices. By default Traccar would do a database request to identify unknown device. If you have a lot of unknown devices, it might be useful to enable this flag to avoid frequent database requests.

database.registerUnknown config

Boolean flag to enable automatic registration of unknown devices.

database.xml config

Boolean flag to save attributes in XML format instead of default JSON format. Note that default web interface won't work with XML format.

database.saveOriginal config

Boolean flag to save original message from device in HEX format in position attributes.

database.historyDays config

Number of days to store position and event history. By default Traccar doesn't clear any old data from the database.

database.selectDevicesAll config

SQL query to select list of GPS tracking devices. Query need to return at least two fields:

  • id - long integer value, identifier of the device in the database
  • deviceId - string, unique identifier of the device, usually IMEI number
database.insertPosition config

SQL query to insert a single position record into the database. Following named parameters (must have colon prefix) are available:

  • deviceId - device identifier in the database (same as 'id' in database.selectDevice)
  • fixTime - date and time of the position fix
  • valid - true if location is accurate, false if location is incorrect or not accurate
  • latitude - latitude reported by the GPS device
  • longitude - latitude reported by the GPS device
  • speed - speed value in knots
  • course - heading/bearing in degrees
  • address - resolved address of the location (requires geocoder to be enabled)
  • protocol - name of the protocol
  • other - other data in XML format (for example, <info><odometer>1000</odometer></info>)
database.updateLatestPosition config

SQL query to update database with latest info from device. In addition to all named parameters from database.insertPosition, there is 'id' parameter that returns automatically generated identifier of the position record returned by database.insertPosition query.

database.[query name] config

Other SQL queries required for JSON API and web interface.

[protocol].port config

Port number for the protocol. Most protocols use TCP on the transport layer. Some protocols use UDP. Some support both TCP and UDP.

[protocol].timeout config

Connection timeout value in seconds. Because sometimes there is no way to detect lost TCP connection, old connections stay in open state. On most systems there is a limit on number of open connection, so this leads to problems with establishing new connections when number of devices is high or devices data connections are unstable.

globalsat.format0 config

First message format for GlobalSat protocol. Default value is 'TSPRXAB27GHKLMnaicz*U!'.

globalsat.format1 config

Second message format for GlobalSat protocol. Default value is 'SARY*U!'.

gt06.timezone config

Timezone offset value (in seconds) for GT06 protocol.

coordinates.filter config

Replaces position coordinates if it changes less than a "coordinates.error" meters. Helps to avoid coordinates jumps during parking period.

coordinates.minError config

Distance in meters. Distances below this value gets handled like explained in "coordinates.filter".

coordinates.maxError config

Distance in meters. Distances above this value gets handled like explained in "coordinates.filter", but only if Position is also marked as "invalid".

event.enable config

Enable events subsystem.

event.overspeed.notRepeat config

If true, the event is generated once at the beginning of overspeeding period.

speedLimit server device group

Speed limit in knots, for device, group or whole server.

deviceManager.lookupGroupsAttribute config

Lookup group tree for attributes happened only if it is enabled.

event.motion.speedThreshold config

If device speed less than its value, device is considered to be stopped. Default is 0.01 knots.

forward.enable config

Enable positions forwarding to other web server.

forward.url config

URL to forward positions. Data is passed through URL parameters. For example, {uniqueId} for device identifier, {latitude} and {longitude} for coordinates.

event.forward.enable config

Enable events forwarding to other web server.

event.forward.url config

URL to forward events.

event.forward.header config

Additional HTTP header, can be used for authorization.

mail.smtp.host config user

SMTP server host name to send notifications.

mail.smtp.port config user

SMTP server port, 25 by default.

mail.smtp.starttls.enable config user

Enables STARTTLS, usually used in combination with 587 port.

mail.smtp.starttls.required config user

If true, requires the use of the STARTTLS command. If the server doesn't support the STARTTLS command, or the command fails, the send will fail.

mail.smtp.ssl.enable config user

Enables SSL, usually used in combination with 465 port.

mail.smtp.ssl.trust config user

If set to "*", all hosts are trusted. If set to a whitespace separated list of hosts, only those hosts are trusted.

mail.smtp.ssl.protocols config user

Specifies the SSL protocols that will be enabled for SSL connections.

mail.smtp.from config user

From address, obligatory for some mail servers.

mail.smtp.auth config user

Enable SMTP authorization.

mail.smtp.username config user

Username for SMTP authorization.

mail.smtp.password config user

Password for SMTP authorization.

templates.rootPath config

Path to the templates root folder.

report.trip.minimalTripDuration config

Trips less than minimal duration and minimal distance are ignored. 300 seconds and 500 meters are default.

report.trip.minimalTripDistance config

Trips less than minimal duration and minimal distance are ignored. 300 seconds and 500 meters are default.

report.trip.minimalParkingDuration config

Parking less than minimal duration does not cut trip. Default 300 seconds.

report.trip.greedyParking config

If true, the device is considered to be in parking state and only continuous trips are detected.

report.trip.useIgnition config

Use ignition value to detect stops.

wialon.utf8 config

Use UTF8 to handle messages from wialon devices.

status.timeout config

Status timeout in seconds. If device does not send data for the specified period of time, the status changes to "unknown".

sms.smpp.enable config

Enables SMPP client for SMS sending

sms.smpp.version config

Sets SMPP protocol version. Default is 3.4

sms.smpp.host config

Hostname or ip address of SMPP server. Default is localhost.

sms.smpp.port config

Port of SMPP server. Default is 2775.

sms.smpp.username config

Username (System Id) to bind to SMPP server

sms.smpp.password config

Password to bind to SMPP server

sms.smpp.sourceAddress config

Source address, usually overridden by SMPP server, but some times must be not empty

sms.smpp.commandSourceAddress config

Source address used for commands only. Used sms.smpp.sourceAddress if omitted.

sms.smpp.notificationsCharset config

Charset name in that notification will be encoded before send. Default is "UCS-2". List is here.

sms.smpp.notificationsDataCoding config

dataCoding used for notification SMS sending. Default is 8. List is here.

sms.smpp.commandsCharset config

Charset name in that command will be encoded before send. Default is "GSM". List is here.

sms.smpp.commandsDataCoding config

dataCoding used for command SMS sending. Default is 0. List is here.

sms.smpp.submitTimeout config

Timeout for submitting SMS to SMPP server in ms. Default is 10000 ms

sms.smpp.sourceTon config

Source address TON. Default is 5. List is here.

sms.smpp.commandSourceTon config

Source address TON used for commands only. Used sms.smpp.sourceTon if omitted.

sms.smpp.sourceNpi config

Source address NPI. Default is 0. List is here.

sms.smpp.commandSourceNpi config

Source address NPI used for commands only. Used sms.smpp.sourceNpi if omitted.

sms.smpp.destTon config

Destination address TON. Default is 1. List is here.

sms.smpp.destNpi config

Destination address NPI. Default is 1. List is here.

sms.smpp.enquireLinkPeriod config

Period of sending enquire link (keepalive) packets in ms. Default is 60000 ms.

sms.smpp.enquireLinkTimeout config

Timeout for enquire link (keepalive) packets in ms. Default is 10000 ms.

sms.smpp.reconnectionDelay config

Delay for reconnection try in ms. Default is 10000 ms.

sms.smpp.logPdu config

Log all communication packets between traccar and SMPP server. Not recommended for production because of huge amount of data.