84 lines
5.7 KiB
Markdown
84 lines
5.7 KiB
Markdown
# NetBox GeoFeed Web Application
|
|
|
|
## Overview
|
|
|
|
This web application provides a self-published IP geolocation feed, conforming to the standards set out in [RFC 8805](https://www.rfc-editor.org/rfc/rfc8805). 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](https://github.com/FrumentumNL/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.
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
For more information about configuring and using this application, please refer to the official .NET documentation and the NetBox API guide.
|