Skip to content

Commit

Permalink
Spell checking and formatting
Browse files Browse the repository at this point in the history
  • Loading branch information
WillT93 committed Aug 11, 2024
1 parent 8192773 commit 0b571b9
Show file tree
Hide file tree
Showing 6 changed files with 28 additions and 15 deletions.
4 changes: 2 additions & 2 deletions Docs/TRACK/ACCESS.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# 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).
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 unlikley to be torn down.
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.

Expand Down
20 changes: 13 additions & 7 deletions Docs/TRACK/FIREWALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ There are two steps to this, the first is the firewall within the cloud provider
## 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 vavigate to the detail page for the virtual machine you are interested in. Click on the "Virtual Cloud Network" associated with the VM.
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.

Expand All @@ -18,25 +18,31 @@ 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 telemetary 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.

* 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 WebUI. 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.

* 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 necissary 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.

* 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 | |
| 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 documenation 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.
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`\
Expand Down
2 changes: 1 addition & 1 deletion Docs/TRACK/INSTALL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# 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 maintainance 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.
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.

Expand Down
1 change: 1 addition & 0 deletions Docs/TRACK/OPTIMIZE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,5 @@ As such, additional steps are recommended to optimize performance and provide so
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.
5 changes: 3 additions & 2 deletions Docs/TRACK/README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
# Tracking
## Overview
The tracking component actually has very little dependance on this project itself. This project does not provide a means to build any custom tracking hardware, which must be purchased seperately, and the extent of the "integration" this project provides for that hardware is simply to pass through +12V (Const & Acc) and GND.
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 necissary 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.
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.
11 changes: 8 additions & 3 deletions Docs/TRACK/SERVER.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 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 propitary 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.
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.

Expand All @@ -17,24 +17,29 @@ As this document is targeted towards a use-case involving dedicated hardware, it
## 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 telemetary 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.
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 Infrastrucre. Many of these providers offer a free teir 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.
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]()

0 comments on commit 0b571b9

Please sign in to comment.