GeoFeed/README.md

NetBox GeoFeed Web Application

Overview

This web application provides a self-published IP geolocation feed, conforming to the standards set out in RFC 8805. It is designed to interface with NetBox, a web-based infrastructure resource modeling (IRM) tool, to retrieve and format geolocation data for IP addresses.

The application is implemented in C# using .NET 8.0, ensuring a robust and modern back-end architecture. It's built to communicate securely over HTTPS with the NetBox API, adhering to best practices for data transmission and security.

This project was inspired by the GitHub project GeoBox, which provided foundational ideas for the development of this application.

Application Variants

AS1024.GeoFeed - MVC Version (Recommended)

The standard version of this application, named AS1024.GeoFeed, is built using the Model-View-Controller (MVC) architecture. This variant is fully supported and recommended for most use cases. It offers a complete set of features and is optimized for robustness and scalability.

AS1024.GeoFeed.MinimalAPI - MinimalAPI Version (Experimental)

In addition to the standard MVC version, there is an experimental MinimalAPI version of the application named AS1024.GeoFeed.MinimalAPI. This variant is designed for environments that require extremely fast startup times, such as serverless containers. However, it comes with limited support and a reduced feature set. We recommend using the AS1024.GeoFeed.MinimalAPI version only if your deployment environment necessitates near-instant startup times and you are comfortable with its experimental nature and limitations.

Note: While the AS1024.GeoFeed.MinimalAPI version offers performance benefits in specific scenarios, we strongly recommend deploying the AS1024.GeoFeed MVC version for most applications to ensure full functionality and support.

Features

• GeoFeed Generation: Dynamically generates a geolocation feed in CSV format as specified in RFC 8805.
• Caching Mechanism: Implements an efficient caching strategy to reduce redundant API calls and enhance performance.
• Local Disk Fallback Caching Mechanism: In the event of a failure to communicate with the NetBox instance specified, the web app will return data that is locally cached inside a SQLite database. In the minimal API version of the GeoFeed application, this will be stored as a file, rather than a SQLite database as Minimal API does not yet support Entity Framework Core at this time.
• Secure Communication: Ensures secure data retrieval from NetBox over HTTPS.

Configuration

The application requires the following configuration variables to be set, depending on the version you are using:

For AS1024.GeoFeed - MVC Version

1. APIKey: This is the API key used for authenticating with the NetBox API. Ensure this key has the necessary permissions to access the required resources.
2. NetBoxHost: The hostname of the NetBox instance from which the application retrieves data. For example, netbox.example.com.
3. LocalFeedCache: This connection string is for a local SQLite Database (using EF Core) that caches the geofeed data from Netbox. The syntax should follow the standard SQLite EF Core connection string format.

For AS1024.GeoFeed.MinimalAPI - MinimalAPI Version

1. APIKey: This is the API key used for authenticating with the NetBox API. Ensure this key has the necessary permissions to access the required resources.
2. NetBoxHost: The hostname of the NetBox instance from which the application retrieves data. For example, netbox.example.com.
3. TempCache (optional): This configuration is specific to the Minimal API version. It is optional, but if users wish to specify a different location for storing and serving the cached geofeed data, this value can be adjusted to point to the desired save location.

These variables can be set in your application's configuration file or through environment variables, depending on your deployment strategy.

NetBox Custom Fields

Ensure that your NetBox instance is configured with the following custom fields:

• geoloc_city: (Text) Represents the city and is not required to be filled in.
• geoloc_country: (Selection) Represents the country and is not required to be filled in.
• geoloc_has_location: (Boolean) Indicates if there is geolocation data available and is required.
• geoloc_postal_code: (Text) Represents the postal code and is not required to be filled in.
• geoloc_region: (Selection) Represents the region and is not required to be filled in.

These fields are critical for the application to accurately retrieve and format geolocation data.

Getting Started

To build and run the application, follow these steps:

1. Ensure you have .NET 8.0 SDK installed on your machine.
2. Clone the repository to your local machine.
3. Navigate to the root directory of the project via a command line interface (CLI).
4. Run the command dotnet build to build the application. This will compile the source code and prepare it for execution.
5. After a successful build, you can start the application by running dotnet run.
6. The application will start, and you can access the endpoints as specified.

Building a Docker Image

Building a Docker Image for the Minimal API Version

To containerize the AS1024.GeoFeed version using Docker, you can follow these steps to build a Docker image:

1. Open your terminal or command line interface.
2. Navigate to the root directory of this repository.
3. Execute the following Docker build command: docker buildx build --platform=linux/amd64,linux/arm64 -f .\AS1024.GeoFeed\Dockerfile .

Building a Docker Image for the Minimal API Version

To containerize the AS1024.GeoFeed.MinimalAPI version using Docker, you can follow these steps to build a Docker image:

1. Open your terminal or command line interface.
2. Navigate to the root directory of this repository.
3. Execute the following Docker build command: docker buildx build --platform=linux/amd64 -f .\AS1024.GeoFeed.MinimalAPI\Dockerfile.alpine-selfcontained .

Currently the minimal API version does not support being cross compiled for different CPU architectures. It is best built with the same CPU architecture where the build machine is targeting to.

Ensure you have Docker installed and configured on your machine before executing this command. This Docker image can then be used to deploy the application in containerized environments such as Kubernetes or Docker Compose setups.

Docker Deployment

To deploy the Docker container of this GeoFeed application, simply pull the image for the following variants:

• MVC Variant docker pull git.startmywifi.com/as1024/geofeed:latest
• Minimal API Variant docker pull git.startmywifi.com/as1024/geofeed:aot-minimal

To configure the container, please refer to the Configuration section above. You should be able to configure this with either an environment variable or map an appSettings.json file to the container.

Endpoints

The application provides the following key endpoints:

• /geofeed: Returns the GeoFeed data in CSV format.
• /geofeed.csv: Also returns the GeoFeed data in CSV format, typically used for downloading the file.

Security and Compliance

This application is designed to always communicate over HTTPS with NetBox, ensuring that the data transfer is encrypted and secure.

Extending Beyond NetBox

If your current IPAM solution is not netbox and wish to extend this web application to use the desired IPAM solution of choice, the interface IGeoFeedProvider is available for extensibility. To use your custom IPAM backend ensure that NetboxAoTGeoFeedProvider and NetboxGeoFeedProvider are not registered in the dependency injection container in the Web Apps. Once unregistered, register your custom IPAM communication backend provider to your needs and the web app should work in both AOT and MVC mode.

Currently the Minimal API implementation of this web application only supports code that does not require reflection. This is a known limitation of native AOT deployments. If your code utilizes reflection or is not properly adapted for source generation, the minimal API version will not work.