Merge pull request #13 from WMTaylor3/feature/tracking-documentation

Document Tracking Accessory

Docs/OPERATION.md

@@ -3,7 +3,7 @@ For using the device once it's been installed
 
 ## Standard Behavior
 ### Tracker
-Addition of a GPS tracker to this project is optional. If desired, one can be connected by way of the "Tracker" header on the PCB. If supplied, the tracker will receive power from the external battery at all times, regardless of the car being at home, away, driving or stopped. Generally these trackers are designed to use minimal amounts of power and so cause negligible drain on the external battery. For more information on integrating a tracker with this project, refer to the [TRACKER.md](Tracker) documentation.
+Addition of a GPS tracker to this project is optional. If desired, one can be connected by way of the "Tracker" header on the PCB. If supplied, the tracker will receive power from the external battery at all times, regardless of the car being at home, away, driving or stopped. Generally these trackers are designed to use minimal amounts of power and so cause negligible drain on the external battery. For more information on integrating a tracker with this project, refer to the [Tracking](TRACK) documentation.
 
 ### 5V Output
 A switched 5V output is also supplied as part of this project by way of the 2 pin header labelled 5V. This output is supplied from the external battery provided there is something connected to the 5V header. (Note, if using the PCB revision intended for use without an additional battery, this 5V output is supplied by way of a 12V to 5V converter drawing power from the cars own battery). The output to this header is switched on and off in sync with the 12V output to the dash cam. A potential use for this output (and the one I intend to implement) is to power a USB 4G to WiFi dongle. This will ensure that whenever the dash-cam has power, it also has internet connectivity for remote access.

Docs/TRACK/ACCESS.md

@@ -0,0 +1,12 @@
+# Access
+With the VM stood up in your cloud provider of choice and appropriately firewalled and optimized it's time to access it for the first time. In the case of most cloud providers, a VM will be assigned a static IP (or something similar).
+
+For Oracle, unless otherwise specified, a VM will receive a public IP which is static for the duration of its life. The IP will persist between reboots of the VM, however if the VM is ever removed entirely, the IP will be unassigned. This should never really present a problem for this purpose as the VM, once stood up, is unlikely to be torn down.
+
+If desired, one can always purchase a domain name and create a DNS entry that points to this IP. That's optional and outside the scope of this guide, but feel free to look into it if desired. Cloudflare is a powerful and popular provider for these purposes.
+
+The IP of the VM can be found in its description page, the exact location will vary depending on the service provider you use. For Oracle go to the VMs **Instance Details** page, and then look under heading **Primary VNIC** subheading **Public IPv4 address**.
+
+Take that IP and paste it into the URL of your web browser with `:8082` appended to it. For example, if the IP was `180.25.113.6` you would enter `180.25.113.6:8082` into your browser.
+
+This will take you to the Traccar page where you can create an account and sign in. At present you'll have no devices set up. This will be covered next in the hardware set up section.

Docs/TRACK/FIREWALL.md

@@ -0,0 +1,58 @@
+# Firewall
+All cloud providers will offer some form of firewalling in order to protect your VPS. This firewall will need to be adjusted to restrict traffic from any unwanted sources/ports and to ensure it doesn't interfere with Traccar traffic.
+
+There are two steps to this, the first is the firewall within the cloud provider, the second is the firewall on the OS of your VM 9will vary between OS).
+
+## OCI Firewall
+If using OCI (Oracle Cloud Infrastructure), you'll need to take the following steps to configure the firewall correctly.
+
+Within the Oracle Cloud Web UI navigate to the detail page for the virtual machine you are interested in. Click on the "Virtual Cloud Network" associated with the VM.
+
+On the Virtual Cloud Network (VCN) detail page, click on the "Security Lists" link.
+
+Click on the default security list, assuming you are using that list.
+
+Click the "Add Ingress Rule" button.
+
+Enter the details of the new rule and click the "Add Ingress Rules" button.
+
+The rules to add/modify are below but will need to be modified for your case as follows:
+* The port `5030` will vary depending on the tracking hardware you select. These are all listed in the Traccar website or shown on the hardware manufacturers page. 5030 is correct for the hardware recommended in this project.
+
+* This rule is responsible for allowing access to the telemetry port so that Traccar may receive updates from the hardware. The source is set to allow all IPs as most cell providers will not provide a static IP for a 4G device.
+
+* The IP `9.9.9.9/32` for the rule with port `8082` will need to be replaced with the static IP of your home network (if you have one) or changed to `0.0.0.0/0` (allow all) if you do not have a static.
+
+* This rule is responsible for restricting access to the Traccar Web UI. the `/32` suffix specifies that only a that single address should be matched, `/0` along with the `0.0.0.0` address indicates all IPs will be permitted.
+
+* Obviously the "Allow all" option is less restricted from a firewall perspective, so it relies entirely on Traccars built in authentication to control access.
+
+* The IP `9.9.9.9/32` for the rule with port `22` will also need to be replaced with your home static IP if available, or replaced with `0.0.0.0/0` if you do not have one. This is for the same reasons specified above.
+
+* This rule is responsible for controlling access to the SSH port of the VM. It is not necessary to have this rule for day-to-day functionality, so if you prefer to use the in-browser SSH terminal or only open this rule when you are doing config changes, that's perfectly reasonable.
+
+| Source          | Protocol | Source Port Range | Destination Port Range | Type and Code |
+| --------------- | -------- | ----------------- | ---------------------- | ------------- |
+| 9.9.9.9/32      | TCP      | All               | 22                     |               |
+| 0.0.0.0/0       | ICMP     |                   |                        | 3, 4          |
+| 10.0.0.0/16     | ICMP     |                   |                        | 3             |
+| 9.9.9.9/32      | TCP      | All               | 8082                   |               |
+| 0.0.0.0/0       | TCP      | All               | 5030                   |               |  
+
+This will sort the firewalling out from the cloud network side. We still need to sort the Ubuntu firewall.
+
+## VM Firewall
+Traditionally Ubuntu hosts use the Uncomplicated Firewall (UFW) as a user-friendly interface to manage the iptables configuration. As explained in the OCI Best Practices documentation page the use of UFW is discouraged because it can lead to serious trouble. UFW is therefore disabled by default. This might catch experienced admins by surprise if they try to open ports via UFW but don’t succeed connecting to the application and cause issues along the way.
+
+Rather than using UFW, a more direct manipulation of the iptables configuration is necessary. The easiest way to do so is modifying /etc/iptables/rules.v4. The easiest way is to copy the line allowing SSH access and modify the newly copied line to accept traffic for port 8082 and 5030 (again, changing 5030 as needed if your GPS hardware uses a different port)\
+`-A INPUT -p tcp -m state --state NEW -m tcp --dport 8082 -j ACCEPT`\
+`-A INPUT -p tcp -m state --state NEW -m tcp --dport 5030 -j ACCEPT`
+
+Please ensure the previous line allowing SSH access is still in place or you will be locked out of your system. The line that absolutely has to remain intact reads\
+`-A INPUT -p tcp -m state --state NEW -m tcp --dport 22 -j ACCEPT`
+
+Once the rule is added it can be enabled using the following command\
+`$sudo iptables-restore < /etc/iptables/rules.v4`
+
+Confirm the configuration by running\
+`$ sudo iptables -L INPUT`

Docs/TRACK/HARDWARE.md

@@ -0,0 +1,8 @@
+# Hardware
+
+## Overview
+
+## Recommended Hardware
+
+## Initial Configuration
+

Docs/TRACK/INSTALL.md

@@ -0,0 +1,50 @@
+# Installation
+This process has been tested on both Google Cloud and Oracle Cloud Infrastructure (OCI). Both providers offer a free tier with sufficient resources to provision a Traccar Server VM. This guide was written during the OCI deployment, more specifically using an Ubuntu VM server, and so covers that provider and OS more specifically. Some sections will need to be adapted slightly should you choose to use another cloud service provider or operating system.
+
+This guide will not cover the process of registering for an account, nor provisioning the VM. These are processes that both change regularly, increasing the maintenance  requirement of this guide. Plenty of resources exist out there instructing you on how to do both of these tasks with the provider of your choice.
+
+Return to this guide once your VPS (VM) is spun up on your cloud provider and you have SSH access to it.
+
+With an Ubuntu VPS set up in your provider of choice, run the below commands to set up the Traccar server.
+
+Install unzip utility and MySQL server\
+`$ sudo apt update`\
+`$ apt -y install unzip mysql-server`
+
+Set database password and create a new database, substituting a fresh password where indicated\
+`$ sudo mysql -u root --execute="ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '[insert-password-here]'; GRANT ALL ON *.* TO 'root'@'localhost' WITH GRANT OPTION; FLUSH PRIVILEGES; CREATE DATABASE traccar;"`
+
+Download the latest installer\
+`$ sudo wget https://www.traccar.org/download/traccar-linux-64-latest.zip`
+
+Unzip the file and run the installer\
+`$ sudo unzip traccar-linux-*.zip`\
+`$ sudo ./traccar.run`
+
+Update the configuration file to use MySQL database\
+`$ cd /opt/traccar/conf`\
+`$ sudo nano traccar.xml`\
+Paste in the below, substituting the password where specified:
+```
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE properties SYSTEM 'http://java.sun.com/dtd/properties.dtd'>
+<properties>
+
+    <!-- Documentation: https://www.traccar.org/configuration-file/ -->
+
+    <entry key='database.driver'>com.mysql.cj.jdbc.Driver</entry>
+    <entry key='database.url'>jdbc:mysql://localhost/traccar?serverTimezone=UTC&amp;allowPublicKeyRetrieval=true&amp;useSSL=false&amp;allowMultiQueries=true&amp;autoReconnect=true&amp;useUnicode=yes&amp;characterEncoding=UTF-8&amp;sessionVariables=sql_mode=''</entry>
+    <entry key='database.user'>root</entry>
+    <entry key='database.password'>[db-password-from-before]</entry>
+
+</properties>
+```
+
+Start the Traccar service\
+`$ sudo service traccar start`
+
+To view the Traccar logs
+`$ tail -f /opt/traccar/logs/tracker-server.log`
+
+To stop the Traccar service\
+`$ sudo service traccar stop`

Docs/TRACK/OPTIMIZE.md

@@ -0,0 +1,10 @@
+# Optimization for Crash Prevention
+The free tier of both Google Cloud and OCI offer machines limited to 1GB of RAM. While this is technically sufficient to host Traccar, in both cases under the default config the system encountered issues with memory exhaustion leading to a total VM crash within 2 days. This could be seen happening in each instance both via the Cloud providers resource monitor and also within the VM by running `htop`.
+
+As such, additional steps are recommended to optimize performance and provide some additional breathing room. Once implemented, memory consumption drops to approximately 500-600MB and the system remains online for (at the time of writing) indefinitely.
+
+There are two layers to this. The first is to provide a swap area on your VM for it to offload memory contents to when needed. The second is to disable the performance schema of the SQL database running alongside Traccar.
+
+1) [Swap](SWAP.md) - for adding swap to your VM.
+
+2) [SQL](SQL.md) - for disabling the SQL performance schema.

Docs/TRACK/README.md

@@ -0,0 +1,15 @@
+# Tracking
+## Overview
+The tracking component actually has very little dependence on this project itself. This project does not provide a means to build any custom tracking hardware, which must be purchased separately, and the extent of the "integration" this project provides for that hardware is simply to pass through +12V (Const & Acc) and GND.
+
+If the tracking functionality is all that you are after, there is no requirement to explore the rest of the repository, however, this README article may still provide value. It offers a recommendation for specific off the shelf hardware and open source software, as well as detailed instructions around setting these both up.
+
+## Guides
+* [Server](SERVER.md) - for instructions on setting up and configuring the server software
+
+* [Hardware](HARDWARE.md) - for hardware recommendation, installation and configuration
+
+Once the server has been configured, the hardware acquired and the necessary configurations applied to link the two. You should be able to access the Traccar Web UI at any time to monitor the location of the vehicle.
+
+## Home Assistant
+If you use Home Assistant, an integration for the Traccar server can be found [here](https://www.home-assistant.io/integrations/traccar_server/) which will enable you to view the vehicles location on your Home Assistant map.

Docs/TRACK/SERVER.md

@@ -0,0 +1,45 @@
+# Server
+## Overview
+While many tracking software suites exist, the idea here is to avoid any kind of commercial offering which incur either large up-front costs or monthly subscriptions or require expensive proprietar hardware. It is also important to avoid going too far in the other direction and getting some cheap device from the local hobby store which will drain the battery in a day and offer limited functionality and integration.
+
+One great option is [Traccar](https://www.traccar.org/). This software is open source, free to use, has been around since 2009, and supports more than 2,000 different models of GPS hardware. It also supports integration with Home Assistant if that's important to you.
+
+There are three main components to the Traccar software suite, the server, the manager and the client.
+
+* Traccar Server is the main software which include the back-end for device communication and the front-end web interface for managing the GPS tracking devices.
+
+* Traccar Manager is a mobile based front end application which can be used to manage GPS tracking devices.
+
+* Traccar Client is a mobile based application which acts as an alternative to GPS tracking hardware and can be used to report the mobile phone's location to the Traccar Server.
+
+As this document is targeted towards a use-case involving dedicated hardware, it will skip over the Traccar Client. The Manager is also outside the scope of this document as, while it may be used with this installation, it is not required. The Traccar server offers a basic Web UI in which the user can view their devices, by integration with Home Assistant, the devices can be surfaced in there too.
+
+## Hosting Options
+Traccar does offer the option to pay them a monthly fee to make use of hosting service they provide. You can pay a reduced fee for your own account on a shared server, with a relatively small device limit (starting at "up to 5 devices"). This is the most basic and reliable option, it is also fairly reasonably priced. If you don't mind paying the subscription cost, it's not a bad option. Targeted more towards commercial customers with fleet tracking needs is the option to pay a higher fee for your own dedicated server, the starting tier in this case is "up to 50 devices". In the case of this project however, while the account offering is tempting, the use case here is only tracking a single vehicle, not 5, and as Traccar is good enough to offer their software open source for anyone to use, with a bit of extra work, a free solution can be devised.
+
+Another option would be to self-host on a server at home, assuming you have a static IP. The issue with this is that it does require opening up a hole in ones home firewall and forwarding a specific port to the Traccar machine. This is fairly unavoidable as the tracking hardware **needs** to communicate with the server, and it **needs** a port open to do this. GPS hardware is usually fairly basic so there's no option of having it connect to a self hosted VPN or anything like that. In truth, the Traccar software is pretty robust, exposing a port to it for receiving GPS telemetry is unlikely to present any real security risk, so by all means pursue this if you wish. Firewall rules and/or VLANs can further isolate the Traccar server in the event it is compromised. If that option doesn't appeal to you, you don't have a machine for 24/7 self hosting, or you don't have a static IP, there is an additional option which takes the advantages of the ones already explored with none of the compromises.
+
+Rather than hosting the server within ones own network, and thus punching a hole in their firewall, these days it's easier than ever to spin up a VM instance on a cloud provider such as, Azure, AWS, Google Cloud, or Oracle Cloud Infrastructure. Many of these providers offer a free tier with limited resources in which you won't get charged for your use. Fortunately, these resources are still plenty to run a very lightweight Traccar instance making it ideal for this use case. They are also available with static IPs, making them ideal for both access by the user and also for the GPS tracker to reach out to. Finally, they present no compromises to ones home network security or need for any kind of in-house hosting hardware. It is this option that the remainder of this document focuses on.
+
+## Guides
+Follow these in the order specified below.
+1) [Install](INSTALL.md) - for the installation of the software within the VM.
+
+2) [Firewall](FIREWALL.md) - for the configuration of the firewall both on the cloud provider and within the VM.
+
+3) [Optimize](OPTIMIZE.md) - for the optimization required to ensure the VM doesn't crash within a few days.
+
+4) [Access](ACCESS.md) - for instructions on accessing Traccar Web UI.
+
+## Useful resources
+These resources are the source of much of the processes and fixes documented above. Refer to them for further information and to give credit to the original authors.
+* Installation:
+  * [VPS Installation](https://www.traccar.org/install-digitalocean/)
+
+* Firewalling:
+  * [OCI & VM](https://blogs.oracle.com/developers/post/enabling-network-traffic-to-ubuntu-images-in-oracle-cloud-infrastructure)
+  * [OCI (with images)](https://oracle-base.com/articles/vm/oracle-cloud-infrastructure-oci-amend-firewall-rules)
+
+* Optimization:
+  * [Swap File](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-20-04)
+  * [SQL]()