diff --git a/README.md b/README.md index 98e44aa..37b588c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # OwnTracks Recorder -The _OwnTracks Recorder_ is a lightweight program for storing and accessing location data published via MQTT by the [OwnTracks](http://owntracks.org) apps. It is a compiled program which is easily installed and operated even on low-end hardware, and it doesn't require external an external database. +The _OwnTracks Recorder_ is a lightweight program for storing and accessing location data published via MQTT by the [OwnTracks](http://owntracks.org) apps. It is a compiled program which is easily installed and operated even on low-end hardware, and it doesn't require external an external database. It is also suited for you to record and store the data you publish via our [Hosted mode](http://owntracks.org/booklet/features/hosted/). There are two main components: the _recorder_ obtains, stores, and serves data, and the _ocat_ command-line utility reads stored data in a variety of formats. @@ -216,6 +216,30 @@ Publish a location from your OwnTracks app and you should see the _recorder_ rec The location message received by the _recorder_ will be written to storage. +### Launching `ot-recorder` for _Hosted mode_ + +You have an account with our Hosted platform and you want to store the data published by your device and the devices you track. Proceed as follows: + +1. Download the [StartCom ca-bundle.pem](https://www.startssl.com/certs/ca-bundle.pem) file to a directory of choice, and make a note of the path to that file. +2. Create a small shell script modelled after the one hereafter with which to launch the _recorder_. +3. Launch that shell script to have the _recorder_ connect to _Hosted_ and subscribe to messages your OwnTracks apps publish via _Hosted_. + +```bash +#!/bin/sh + +export OTR_USER="username" # your OwnTracks Hosted username +export OTR_DEVICE="device" # one of your OwnTracks Hosted device names +export OTR_TOKEN="xab0x993z8tdw" # the Token corresponding to above pair +export OTR_CAFILE="/path/to/startcom-ca-bundle.pem" + + +ot-recorder --hosted "owntracks/#" +``` + +Note in particular the `--hosted` option: you specify neither a host name or a port number; the _recorder_ has those built-in, and it uses a specific _clientID_ for the MQTT connection. Other than that, there is no difference between the _recorder_ connecting to Hosted or to your private MQTT broker. + + + ## Design decisions We took a number of decisions for the design of the recorder and its utilities: diff --git a/ot-recorder.c b/ot-recorder.c index dd4d37b..4b59277 100644 --- a/ot-recorder.c +++ b/ot-recorder.c @@ -707,6 +707,7 @@ void usage(char *prog) printf(" --doc-root document root (%s)\n", DOCROOT); #endif printf(" --precision ghash precision (dflt: %d)\n", GHASHPREC); + printf(" --hosted use OwnTracks Hosted\n"); printf("\n"); printf("Options override these environment variables:\n"); printf(" $OTR_HOST MQTT hostname\n"); @@ -715,6 +716,10 @@ void usage(char *prog) printf(" $OTR_USER\n"); printf(" $OTR_PASS\n"); printf(" $OTR_CAFILE PEM CA certificate chain\n"); + printf("For --hosted:\n"); + printf(" $OTR_USER username as registered on Hosted\n"); + printf(" $OTR_DEVICE connect as device\n"); + printf(" $OTR_TOKEN device token\n"); exit(1); } @@ -723,10 +728,10 @@ void usage(char *prog) int main(int argc, char **argv) { struct mosquitto *mosq = NULL; - char err[1024], *p, *username, *password, *cafile; + char err[1024], *p, *username, *password, *cafile, *device; char *hostname = "localhost", *logfacility = "local0"; int port = 1883; - int rc, i, ch; + int rc, i, ch, hosted = FALSE; static struct udata udata, *ud = &udata; struct utsname uts; UT_string *clientid; @@ -782,6 +787,7 @@ int main(int argc, char **argv) { "storage", required_argument, 0, 'S'}, { "logfacility", required_argument, 0, 4}, { "precision", required_argument, 0, 5}, + { "hosted", no_argument, 0, 6}, #ifdef HAVE_HTTP { "http-host", required_argument, 0, 3}, { "http-port", required_argument, 0, 'A'}, @@ -796,6 +802,9 @@ int main(int argc, char **argv) break; switch (ch) { + case 6: + hosted = TRUE; + break; case 5: geohash_setprec(atoi(optarg)); break; @@ -849,7 +858,7 @@ int main(int argc, char **argv) usage(progname); exit(0); default: - abort(); + exit(1); } } @@ -862,6 +871,42 @@ int main(int argc, char **argv) return (-1); } + if (hosted) { + char tmp[BUFSIZ]; + + hostname = strdup("hosted.owntracks.org"); + port = 8883; + + if ((username = getenv("OTR_USER")) == NULL) { + fprintf(stderr, "%s requires $OTR_USER\n", progname); + exit(1); + } + if ((device = getenv("OTR_DEVICE")) == NULL) { + fprintf(stderr, "%s requires $OTR_DEVICE\n", progname); + exit(1); + } + if ((password = getenv("OTR_TOKEN")) == NULL) { + fprintf(stderr, "%s requires $OTR_TOKEN\n", progname); + exit(1); + } + if ((cafile = getenv("OTR_CAFILE")) == NULL) { + fprintf(stderr, "%s requires $OTR_CAFILE\n", progname); + exit(1); + } + + utstring_renew(clientid); + utstring_printf(clientid, "ot-RECORDER-%s-%s", username, device); + if (uname(&uts) == 0) { + utstring_printf(clientid, "-%s", uts.nodename); + } + + snprintf(tmp, sizeof(tmp), "%s|%s", username, device); + username = strdup(tmp); + } else { + username = getenv("OTR_USER"); + password = getenv("OTR_PASS"); + } + openlog("ot-recorder", LOG_PID | LOG_PERROR, syslog_facility_code(logfacility)); #ifdef HAVE_HTTP @@ -925,10 +970,8 @@ int main(int argc, char **argv) mosquitto_connect_callback_set(mosq, on_connect); mosquitto_disconnect_callback_set(mosq, on_disconnect); - if ((username = getenv("OTR_USER")) != NULL) { - if ((password = getenv("OTR_PASS")) != NULL) { + if (username && password) { mosquitto_username_pw_set(mosq, username, password); - } } cafile = getenv("OTR_CAFILE"); diff --git a/version.h b/version.h index bb06853..6a68486 100644 --- a/version.h +++ b/version.h @@ -1 +1 @@ -#define VERSION "0.2.2" +#define VERSION "0.2.3"