44Net Wiki - User contributions [en]

Portal intro

2024-10-24T19:13:26Z

W6JMK: link to the API page

=DRAFT - In Progress=

= ARDC Portal 2.0 Technical Documentation =

By Rebecca Key KO4KVG

Version: 4 (October 22, 2024)

== Accessing the Portal ==

Go to [https://portal.ampr.org/home https://portal.ampr.org], where you should see the following UI:

[[File:Portal-homepage-login-v4.png|750px]]

== Registration ==

# Click on the 'Register' button at the top right of the UI (see 'Accessing the Portal', step 1) or on the 'Register' button in the 'LOGIN' dialog box. This will take you to the following screen: [[File:Registration-step-1-of-3-v4.png|750px]]
# Complete the field for 'What should we call you?:' and click 'Continue'.
# In the dialog box titled 'Registration (Step 2/3)', you will be introduced to help icons ('?') that will provide you useful information throughout the Portal. Click 'Close' to exit the dialog box. [[File:Registration-step-2-of-3-popup-box-v4.png|740px]] From there, you enter your Given name, Family name, email address, a username (used to login) and a password, then click 'Continue'. [[File:Registration-step-2-of-3-v4.png|750px]]
# You should then arrive at a dialog box titled 'Registration (Step 3/3)' that displays the End User License Agreement (EULA). Read through the EULA, and if you agree to the terms and conditions, tick both 'I AM 18 YEARS OF AGE OR OLDER', and 'I accept and agree to the terms of this End User License Agreement', and then click 'I Accept'. Note that if you are under the age of 18, and/or if you do not agree with the Terms of Use, then you will not be able to use the Portal. [[File:Registration-step-3-of-3-v4.png|750px]]
## Note: When you log back in on a later date, you might get a notice about the addition and/or updates to the EULA. For example, if you see a dialog box titled 'The EULA has been updated', verify that you are 18 or older, and if you would like to continue using the Portal, accept the updated EULA.
# Upon accepting the Terms of Use, you should get a message (see below) informing you that the system is sending you an email verification with further instructions. Follow the instructions in this email. [[File:Verify-email-v4.png|750px]]
# Once you complete the instructions in the email, you should get a page that looks like the one below, which will have an alert entitled 'You successfully verified your email'. Fill in the information in the 'LOGIN' dialog box and click 'Login'. [[File:email-verified-v3.png|750px]]
# From there, you will be prompted to click 'Continue Registration'. [[File:Continue-registration-v4.png|750px]]
# Once you click 'Continue Registration', you will be brought to a page where you will be asked to complete registration. [[File:Complete-registration-form-v4.png|750px]]
# Confirm that the required information is correct; add any optional information you prefer to share; read and agree to the 'Terms and Conditions', and click the 'Continue' button. You should then see a page that shows 'Registration Complete', which includes a note to verify your call sign as the next step. [[File:Registration-complete-v4.png|750px]]
# To add and verify your call sign, go to the 'Account' dropdown menu and select 'Call signs'. You should see the 'Your call signs' dialog box. [[File:Your-call-signs-v4.png|750px]] Click 'Add a call sign', where you will see a form to add your call sign. Enter your call sign in the input field and click 'Add'. [[File:Add-a-call-sign-v4.png|750px]] You should then see a message stating 'The new call sign was successfully added'. [[File:Call-sign-successfully-added-v4.png|750px]] Clicking the 'Make Primary' button will make a desired call sign the primary call sign on the account, and you can delete a call sign from your account by simply clicking the 'Delete' button.
## If you did not add your maidenhead to your profile, you will get a message at the top of the page stating: [[File:Add-maidenhead-error-prompt-v4.png]] above the 'Update your profile' form. [[File:Update-your-profile-maidenhead-v4.png|750px]] Add your maidenhead, confirm your password, and click 'Save'.
## You will then see the following message above the 'Update your profile' form: [[File:profile-updated-ok-message-v4.png|500px]]
## Go back to Step 10, where you'll be prompted to add your call sign. 
# On the 'Your call signs' UI, click 'Verify'. This will take you to a screen that details the process of verification. [[File:Verify-call-sign-prompt-2-v4.png|750px]]
# Click on the green 'Verify' button: you should see an alert saying 'Your request to verify your callsign [$call sign] has been submitted', which will create a ticket for the Portal admins to verify your call sign. [[File:Callsign-is-verified-v4.png|750px]] You can check the ticket by going to the 'Tickets' dropdown menu, selecting 'View my tickets', where you see it listed. To see the details of the ticket, click 'View'. [[File:View-ticket-request-details-v4.png|500px]]
## Note that once your call sign has been verified, you will no longer see the ticket in the list. Alternatively, you can confirm that your call sign has been verified by going to 'Account' > 'Call signs', and the status of your call sign verification will be displayed in the 'Your call signs' dialog box. Once your call sign has been verified, you will be able to request address space. [[File:Verified-call-sign-v4.png|750px]]

== Requesting Address Space (Beginner Friendly Steps) ==

This series of steps is aimed at users who are either new to requesting 44Net address space, need a refresher, or would like to streamline the process. Otherwise, you can also request address space via the Network list in the 'Requesting Address Space (via Network List)' and 'Requesting Address Space for BGP Use (via Network List)' sections below.

# Under the 'Networks' menu, select 'Request addresses'. Note that you can also request address space on the Dashboard by clicking 'Request address space'. [[File:request-address-space-dashboard-v4.png|750px]]
# You should see a dialog box entitled 'Request Address Space'. Select your address type (should be IPv4, as IPv6 is not currently available), use case, and click 'Continue'. Please see the below instructions for your particular use case. [[File:Request-address-space-form-v3.png|750px]]

=== Use Case: IPIP Tunnel Mesh, Radio, Globally Unique Space, or General Address Assignment ===

# If you selected IPIP tunnel mesh, radio, globally unique space, or general address assignment as your use case, you will see a dialog box entitled 'Request IP Assignment'. Fill out the 'Request IP Assignment' dialog box with the required information; agree to the EULA; and click 'Continue'. [[File:Request-ip-assignment-v4.png|750px]]
# You will then see the following note thanking you for requesting address space from ARDC, which includes detailed information about next steps. [[File:Ty-for-requesting-address-space-v4.png|750px]]
# Once your address space has been assigned, you can proceed to step 6 under 'Requesting Address Space (via Network List)'.

=== Use Case: BGP Direct Announce ===

#If you selected 'BGP Direct Announce' as your use case, you will see a dialog box entitled 'Request IP Assignment'. Fill out the 'Request IP Assignment' dialog box with the required information, agree to the EULA, and click 'Continue'. [[File:Request-ip-assignment-for-bgp-v4.png|750px]]
# Proceed to step 3 under 'Requesting Address Space for BGP Use (via Network List)'.

=== Other Use Cases ===

Selecting any of the below use cases will give you a dialog box that provides more details about the network:
* AREDN
* HAMNET
* HamWAN

== Requesting Address Space (via Network List) ==

# Under the 'Networks' menu, select 'All IPv4 Networks'.
# In the 'List IPv4 Networks' dialog box, click the + sign to expand a line, or use the 'Expand All' button. [[File:List-ipv4-networks-v4.png|500px]]
# Scroll to look for the address space you are looking for (e.g., 44.63.0.0/16 - IPIP Mesh Assignments) and click on the green clipboard icon to the right of the assignment to request an assignment. [[File:Request-network-assignment-v4.png|750px]]
# Fill out the 'Request IP Assignment' dialog box with the required information, and click 'Continue'. [[File:Request-ip-assignment-v4-via-network-list.png|750px]] You will see the dialog box titled 'Thank you for requesting address space from ARDC' (see step 2 under 'Use Case: IPIP Tunnel Mesh, Radio, Globally Unique Space, or General Address Assignment'), which includes detailed information about next steps.
# To confirm that your address space has been successfully requested, you can go to 'Tickets' > 'View my tickets' to see if the request is in your ticket list. Note that you may be asked to provide more information to the Ticket Handler about your request before your address space is assigned. [[File:Confirm-address-request-in-tickets-v4.png|750px]] [[File:Justification-for-address-space-v4.png|750px]]
# Once your space has been assigned (and the associated ticket has been closed), you can view your IPv4 networks by going to 'Networks' > 'my IPv4 networks', where your network detail(s) will be provided. [[File:Network-detail-of-requested-address-space-v4.png|750px]]

== Adding DNS Records to a Subdomain ==

# On the 'DNS' dropdown menu, select 'My subdomains' and then click 'Request a subdomain' in the 'My subdomains' dialog box. [[File:my-subdomain-dialog-box.png|750px]]
# Choose your domain, determine a name for your subdomain (i.e., most likely your call sign), click 'Create request', and you should see a note [[File:Create-new-subdomain-request-v4.png|750px]] saying 'Subdomain $[call sign].ampr.org has been assigned to you'. [[File:Subdomain-has-been-assigned-to-you-v4.png|750px]] Please be aware that if your call sign has not been verified or if you are requesting a domain other than $[call sign].ampr.org, a ticket will be opened for an administrator to review your request(s). You can verify that your subdomain has been created by going to 'DNS' > 'My subdomains', and your subdomain should appear in the 'My subdomains' dialog box. [[File:Subdomain-creation-verification-v4.png|750px]]
# Once your subdomain has been created, you can add DNS records by going to 'DNS' > 'My subdomains', and click the icon under 'Actions' in the 'Subdomains' dialog box (see step 2 above).
# In the 'Resource records for $subdomain.ampr.org', click 'Add a resource record'. [[File:add-resource-record.png|750px]]
# In the 'Create resource record for $subdomain.ampr.org', select the record type, and click 'Next' (see below). [[File:create-resource-record-step-1.png|750px]]
# Add the details relevant to the record type and ensure that Active is checked, click 'Create', [[File:Create-resource-record-step-2-v4.png|750px]] and you should get an alert that says 'Subdomain Record created successfully'. [[File:Subdomain-record-created-successfully-v4.png|750px]]
# You can verify that your record has been created by going to 'DNS' > 'My records' and look for the record that is associated with your subdomain. [[File:record-associated-with-subdomain.png|750px]]

== Creating a Gateway ==

# Go to 'Networks' > 'My gateways' and click 'Create a Gateway' in the 'My Gateways' dialog box. [[File:my-gateways.png|750px]]
# In the 'Create new Gateway' dialog box, fill out all required fields (Hostname can be left blank), click 'Add', and you should get an alert saying 'Gateway created successfully.' [[File:create-new-gateway.png|750px]] [[File:Gateway-created-successfully-v4.png|750px]]
# To add a subnet to your gateway, click the edit button under 'Actions' (see step 2 above). You will be taken to an 'Update Gateway' dialog box, which includes information about your gateway. Click 'Add New Network'. [[File:Update-gateway-v4.png|750px]]
# You will then see an 'Add New Network' dialog box (see below). Select a network from your list of networks; leave 'Find Network' field blank; and then click 'Add'. You should see an alert titled 'Network Successfully Linked to this Gateway' (see below). You can verify that your network has been added by clicking 'View My Gateways' and seeing said gateway under 'My Gateways' (see below). [[File:add-new-network-v3.png|750px]] [[File:Network-successfully-linked-to-gateway-v4.png|750px]] [[File:verify-my-gateways-v3.2.png|750px]]
# If you would like to add someone else's network using their unique code, click 'Add New Network', which will take you to the 'Add New Network' dialog box. Fill out the required information, and click 'Find'. You should have a 44Net address displaying in the 'Network found' field. Click 'Add', and you should see an alert titled 'Network Successfully Linked to this Gateway' (see step 4 above). [[File:Add-network-to-gateway-v4.png|750px]]
# You can add or remove linked networks by clicking the 'Add New Network' or 'Unlink' button, respectively (see steps 3 and 4 above).

== Requesting Address Space for BGP Use (via Network List) ==

# From the 'Networks' dropdown menu, go to 'All IPv4 networks', and request a BGP assignment (e.g., 44.31.0.0/16 - BGP Assignments) by clicking on the 'Request Assignment' icon to the right of the listed assignment (green clipboard). [[File:Request-bgp-assignment-v4.png|500px]]
# On the 'Request IP Assignment' dialog box, fill out the mandatory fields, agree to the EULA, and click 'Continue'. [[File:Request-ip-assignment-for-bgp-v4.png|750px]]
# You should see a 'BGP Information' dialog box on the UI. Fill out the mandatory information, click 'Submit Request', [[File:Bgp-information-v4.png|750px]] and you should now see 'Thank you for requesting address space from ARDC' (see Step 2 under 'Use Case: IPIP Tunnel Mesh, Radio, Globally Unique Space, or General Address Assignment'). Note that the justification must be at least 100 characters.
# You can confirm the address has been successfully requested by going to 'Tickets' > 'View my tickets', and your request should be visible in the 'List your tickets' dialog box. Once the ticket has been closed, you should see the allocation listed in your IPv4 networks. [[File:all-ipv4-allocations-by-user.png|500px]] Clicking 'Edit' will bring you to the 'Update Network' dialog box, where you can make appropriate updates, download the EULA, download the Letter of Authorization (LOA), etc (see below). [[File:update-network-v3.2.png|750px]]

== v2.0 Features ==

=== Dashboard ===

After logging in, you should see your Dashboard. If your email has been verified, you should see an 'Account' menu and a 'Tickets' menu at the top right-hand side of the UI. If you have been granted additional privileges, you will see additional menus for those related privileges. The Dashboard will also display information boxes, such as your latest login, IP, and timestamp, or outstanding notifications you need to be aware of.

[[File:Dashboard-v4.png|750px]]

=== Help ===

The 'Help' dropdown menu provides the following options:
*'''View EULA''': displays a copy of the Portal's End User License Agreement (EULA)

* '''2FA''': defines 2FA and provides details on multiple 2FA options to choose from to add to your account

* '''LoT''': provides an overview of Level of Trust (LoT), how it works, and how to increase your LoT

* '''CIDR''': provides an overview of Classless Inter-Domain Routing (CIDR)

* '''Limits''': provides an explanation of your specific limits on Portal activities, which are directly related to your current LoT

* '''Member pages''': These are pages generated by other members

* '''Subdomains''': provides an overview of subdomains and DNS and steps needed to request subdomains

* '''Passwords''': provides password requirements and recommendations for how to create a strong password for your Portal account

* '''Glossary''': includes definitions for terminology relevant to using the Portal

* '''Community''': includes links to ARDC's Groups.io group, along with links to relevant subgroups

* '''Lookup callsign''': allows you to look up call signs of other users on the Portal

=== Maps ===

* '''Distance''': allows you to perform distance and bearing calculations

* '''Maidenhead''': allows you to generate a map from a Maidenhead locator

* '''Conversions''': allows you to convert from DMS to lat/long and back

* '''World map''': a map that displays the approximate location for all members

=== Account ===

The 'Account' dropdown menu provides the following options:
* '''Profile''': allows you to view and update your personal data

* '''Call signs''': allows you to add/remove/verify your call sign(s)

* '''LoT entries''': lists your Level of Trust (LoT) entires

* '''Verify address''': allows you to go through the address verification process, which is needed if you are requesting BGP announced address space

* '''Organisations''': allows you to create organizations and view information of the organizations you are affiliated with

* '''Notifications''': displays a list of user notifications

* '''Notification types''': displays all notification types/options

* '''View all notifications''': displays all your active notifications

* '''Logs''': displays all your log entries

* '''My public page''': displays any public pages you have added and provides the ability to add more

* '''Delete my account''': allows a user to delete their account

==== Profile ====

A user's profile is always available, whether or not a their email address has been verified. Through the profile, a user has access to the following:
* Personal Information (PII) a user chooses to share with ARDC

* The ability for a user to update their account

* The ability for a user to enable 2FA on their account

Changes made to the profile will require the current password to be entered at the bottom of the page and clicking 'Save' for changes take effect.

==== Call signs ====

Here, the user is presented with a list of all call signs they have entered. A user can add up to a maximum of five call signs (can be adjusted on a per user basis), with only one call sign being the primary. Clubs and organization can add up to 10 of their own call signs by default. Call signs must be verified before they can be used. All verified call signs must be unique within the system.

==== Level of Trust (LoT) & LoT Entries ====

The Portal uses various methods to verify users and thus gain 'trust', which is referred to as the 'Level of Trust' (LoT). LoT is used to increase confidence that a user is who they say they are and record that there is a skill set and knowledge that is needed to assign responsibilities to said user in the Portal.

As various tasks are accomplished, such as verification of email and/or call signs, points will be assigned to a users' account. The more points a user has, the higher the LoT. You can learn more about LoT by going to either 'Help' > 'LoT' or 'Account' > 'LoT info' on the navigation menu.

The LoT List is a read-only list for LoT entries of a user. You can find this list by going to 'Account' > 'LoT list'. A user will have at least one entry that shows that their email address was verified. Below are a few examples of what accesses are granted based on a user's LoT.

* Email is not verified
** User can login, access their own profile, delete their account
* Call sign is not verified
** User cannot access DNS records or request address space

==== Notifications ====

The system informs users of various events via notifications. [[File:Notification-types-v4.png|750px]]

Mandatory Notifications:
* Contact Member
* Password Reset
* Ticket Reminder
* LoT Expiry
* LoT Added
* Account Expiry
* LOA Expiry

Optional Notifications:
* Login
* Profile Update
* Ticket Assigned
* ...and many more

Clicking on 'Methods' (under the 'Actions' column, see above) will allow the user to choose a preferred method of notification: [[File:notification-methods.png|750px]]

* Email
* SMS
* many more coming soon, e.g. Zulip, Signal, Telegram...

=== Tickets ===

Tickets track tasks, along with their associated progress, within the Portal. Items managed by tickets include, but are not limited to:
* Call sign verification
* Request(s) for resources (e.g., address space)

The 'Tickets' dropdown menu will allow the user to view all of their tickets, create a new support ticket, and serves as a reference to check the status of any user requests.

Ticket types that are not 'Support' are available within the system and are accessible to a user in a specific circumstance.

=== Domain Name System (DNS) Records ===

ARDC manages the ampr.org domain for its own use and supports Portal user needs.

Once a user's call sign is verified, they should see the DNS dropdown menu with submenu options 'Domains', 'My subdomains', and 'My records'.

[[File:dns-menu.png|750px]]

=== Networks ===

Once a user's call sign is verified, they should see the 'Networks' dropdown menu with submenu options 'Request addresses', 'All IPv4 networks', 'All IPv6 networks', 'All gateways', 'My IPv4 networks', 'My IPv6 networks', 'My gateways'.

=== Contact ===

Clicking 'Contact' takes you to the 'CONTACT US' form, where you can reach out to Portal admins with inquiries, reporting issues, etc.

[[File:contact-us-v3.png|750px]]

=== API ===

An [[API]] enables programs to access data maintained in the portal.

== Helpful Resources ==

'''Subnet calculator''': [https://www.calculator.net/ip-subnet-calculator.html https://www.calculator.net/ip-subnet-calculator.html]

Encap.txt/get-encap

2024-10-19T14:59:00Z

W6JMK:

Here's a bash script to get a complete [[encap.txt]] file from the portal.
For example:

./get-encap < api-token.txt > encap.txt || echo error $?

The script maintains a cache, so it downloads the information only when it has changed.

<nowiki>#!/bin/bash
# Output the current AMPRNet routing information, like this:
# # Fetched <when> version <number> from <source>
# route addprivate 44.0.1.0/32 encap 169.228.84.34
# route addprivate 44.102.240.16/28 encap 45.145.74.247
# ...

cache="${1:-routes.json}" # a file that stores previous information
token=`cat -` # an API token
# To obtain a token, register with http://portal.ampr.org/ , log in,
# browse your profile and copy the value of "API Token".
# Be sure to keep the token private. This script won't reveal it.

API="https://portal.ampr.org/api/v2"
# The API returns JSON, something like:
# {
# "count": 836,
# "serial": "136.269",
# "encap": [
# {
# "gatewayIP": "118.82.153.200",
# "encapType": "IPIP",
# "network": "44.147.0.210",
# "cidr": 25,
# ...
# },
# ...
# ]
# }
# ... but without insignificant white space.
# We trust that any change will also change the serial value.

allZero () {
for status in "$@"; do
[ "$status" != 0 ] && return "$status"
done
return 0
}

curlOptions="-s
-S
-f
-H \"Authorization: Bearer $token\"
-H \"Accept: application/json\"
"
if [[ -e "$cache" && ! -f "$cache" ]]; then
echo >&2 `basename "$0"`": $cache isn't a regular file."
exit 1
elif [ -r "$cache" ]; then
oldVersion=`jq -e ".serial" "$cache"` || oldVersion="cache error $?"
[ "$oldVersion" == "null" ] && oldVersion="N/A" # != $newVersion
newVersion=$(
echo "$curlOptions" | curl --config - "$API"/encap/serial | jq -e ".serial"
allZero "${PIPESTATUS[@]}" || exit $?
) || newVersion="API error $?"
else
oldVersion="N/A" # != $newVersion
newVersion="TBD"
fi
# echo "# oldVersion=$oldVersion newVersion=$newVersion"
if [ "$newVersion" != "$oldVersion" ]; then
# Fetch new data from the API and store it in $cache:
newVersion=$(
echo "$curlOptions" | curl --config - "$API"/encap/routes | tee "$cache" | jq -e ".serial"
allZero "${PIPESTATUS[@]}" || exit $?
) || exit $?
fi
# Convert $cache to the output format:
echo "# Fetched" `date -r "$cache"` version "$newVersion" from "$API" || exit $?
jq -e -r '.encap[] | select(.encapType == "IPIP") | "route addprivate \(.network)/\(.cidr) encap \(.gatewayIP)"'\
"$cache" | sort
# Sorting the output makes it easier to compare different versions.
allZero "${PIPESTATUS[@]}" || exit $?
</nowiki>

Encap.txt/get-encap

2024-10-15T19:42:57Z

W6JMK: handle errors from jq

Here's a bash script to get a complete [[encap.txt]] file from the portal.
For example:

.\get-encap < api-token.txt > encap.txt || echo error $?

The script maintains a cache, so it downloads the information only when it has changed.

<nowiki>#!/bin/bash
# Output the current AMPRNet routing information, like this:
# # Fetched <when> version <number> from <source>
# route addprivate 44.0.1.0/32 encap 169.228.84.34
# route addprivate 44.102.240.16/28 encap 45.145.74.247
# ...

cache="${1:-routes.json}" # a file that stores previous information
token=`cat -` # an API token
# To obtain a token, register with http://portal.ampr.org/ , log in,
# browse your profile and copy the value of "API Token".
# Be sure to keep the token private. This script won't reveal it.

API="https://portal.ampr.org/api/v2"
# The API returns JSON, something like:
# {
# "count": 836,
# "serial": "136.269",
# "encap": [
# {
# "gatewayIP": "118.82.153.200",
# "encapType": "IPIP",
# "network": "44.147.0.210",
# "cidr": 25,
# ...
# },
# ...
# ]
# }
# ... but without any insignificant white space.
# We trust that any change will also change the serial value.

allZero () {
for status in "$@"; do
[ "$status" != 0 ] && return "$status"
done
return 0
}

curlOptions="-s
-S
-f
-H \"Authorization: Bearer $token\"
-H \"Accept: application/json\"
"
if [[ -e "$cache" && ! -f "$cache" ]]; then
echo >&2 `basename "$0"`": $cache isn't a regular file."
exit 1
elif [ -r "$cache" ]; then
oldVersion=`jq -e ".serial" "$cache"` || oldVersion="cache error $?"
[ "$oldVersion" == "null" ] && oldVersion="N/A" # != $newVersion
newVersion=$(
echo "$curlOptions" | curl --config - "$API"/encap/serial | jq -e ".serial"
allZero "${PIPESTATUS[@]}" || exit $?
) || newVersion="API error $?"
else
oldVersion="N/A" # != $newVersion
newVersion="TBD"
fi
# echo "# oldVersion=$oldVersion newVersion=$newVersion"
if [ "$newVersion" != "$oldVersion" ]; then
# Fetch new data from the API and store it in $cache:
newVersion=$(
echo "$curlOptions" | curl --config - "$API"/encap/routes | tee "$cache" | jq -e ".serial"
allZero "${PIPESTATUS[@]}" || exit $?
) || exit $?
fi
# Convert $cache to the output format:
echo "# Fetched" `date -r "$cache"` version "$newVersion" from "$API" || exit $?
jq -e -r '.encap[] | select(.encapType == "IPIP") | "route addprivate \(.network)/\(.cidr) encap \(.gatewayIP)"'\
"$cache" | sort
# Sorting the output makes it easier to compare different versions.
allZero "${PIPESTATUS[@]}" || exit $?
</nowiki>

Encap.txt/get-encap

2024-10-15T19:14:09Z

W6JMK: Handle errors returned from the portal API

Here's a bash script to get a complete [[encap.txt]] file from the portal.
For example:

.\get-encap < api-token.txt > encap.txt || echo error $?

The script maintains a cache, so it downloads the information only when it has changed.

<nowiki>
#!/bin/bash
# Output the current AMPRNet routing information, like this:
# # Fetched <when> version <number> from <source>
# route addprivate 44.0.1.0/32 encap 169.228.84.34
# route addprivate 44.102.240.16/28 encap 45.145.74.247
# ...

cache="${1:-routes.json}" # a file that stores previous information
token=`cat -` # an API token
# To obtain a token, register with http://portal.ampr.org/ , log in,
# browse your profile and copy the value of "API Token".
# Be sure to keep the token private. This script won't reveal it.

API="https://portal.ampr.org/api/v2"
# The API returns JSON, something like:
# {
# "count": 836,
# "serial": "136.269",
# "encap": [
# {
# "gatewayIP": "118.82.153.200",
# "encapType": "IPIP",
# "network": "44.147.0.210",
# "cidr": 25,
# ...
# },
# ...
# ]
# }
# ... but without any insignificant white space.
# We trust that any change will also change the serial value.

allZero () {
for status in "$@"; do
[ "$status" != 0 ] && return "$status"
done
return 0
}

curlOptions="-s
-S
-f
-H \"Authorization: Bearer $token\"
-H \"Accept: application/json\"
"
if [[ -e "$cache" && ! -f "$cache" ]]; then
echo >&2 `basename "$0"`": $cache isn't a regular file."
exit 1
elif [ -r "$cache" ]; then
oldVersion=`jq ".serial" "$cache"` || oldVersion="cache error $?"
[ "$oldVersion" == "null" ] && oldVersion="N/A" # != $newVersion
newVersion=$(
echo "$curlOptions" | curl --config - "$API"/encap/serial | jq ".serial"
allZero "${PIPESTATUS[@]}" || exit $?
) || newVersion="API error $?"
else
oldVersion="N/A" # != $newVersion
newVersion="TBD"
fi
# echo "# oldVersion=$oldVersion newVersion=$newVersion"
if [ "$newVersion" != "$oldVersion" ]; then
# Fetch new data from the API and store it in $cache:
newVersion=$(
echo "$curlOptions" | curl --config - "$API"/encap/routes | tee "$cache" | jq ".serial"
allZero "${PIPESTATUS[@]}" || exit $?
) || exit $?
fi
# Convert $cache to the output format:
echo "# Fetched" `date -r "$cache"` version "$newVersion" from "$API" || exit $?
jq -r '.encap[] | select(.encapType == "IPIP") | "route addprivate \(.network)/\(.cidr) encap \(.gatewayIP)"'\
"$cache" | sort
# Sorting the output makes it easier to compare different versions.
allZero "${PIPESTATUS[@]}" || exit $?
</nowiki>

API

2024-10-15T18:50:13Z

W6JMK: document error handling

The AMPRNet [[Portal]] has an associated API that allows the data and functionality of the [[Portal]] to be accessed programatically.

=== Version 1 ===

Version 1 of the API uses a RESTful design, accessible only via SSL (https://) to increase security.

All requests to the API require the client to authenticate by using Basic HTTP authentication,
so you will need a username and password in order to access any part of the API,
this can be obtained by registering for an account on the [[Portal]].

Once you have an account, you can create your API Key (password) from the "Profile' menu link, in the "Security" section.
The API username is the same username you used to login to the [[Portal]] via your web browser.

=== Version 2 ===

Version 2 of the API also uses a RESTful design. Requests and responses are exchanged via HTTPS.
Access is controlled using [https://datatracker.ietf.org/doc/html/rfc6750 Bearer authorization].
So, each request must include an HTTP header like this:

Authorization: Bearer <API Token>

To obtain an API token, register with the [[Portal]], log in,
browse your profile and copy the value of "API Token".

Some responses are in [https://www.json.org JSON] format. Requests should include a header:

Accept: application/json

To get complete current routing information in JSON,
request <nowiki>https://portal.ampr.org/api/v2/encap/routes</nowiki>.
For example, a Unix command like this will output complete current routing information:

curl -s -H "Authorization: Bearer $APItoken" -H "Accept: application/json" <nowiki>https://portal.ampr.org/api/v2/encap/routes</nowiki>

The response includes a serial number, which changes when any route is updated.
To get the current serial number (but not the routes) in JSON,
request <nowiki>https://portal.ampr.org/api/v2/encap/serial</nowiki>.

If something goes wrong, the HTTP response may include
an HTTP status code other than 200
and/or an error message in the body.
For example, a request with an invalid API token will elicit a response including:

<nowiki>HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"message":"Unauthenticated."}</nowiki>

Encap.txt

2024-10-15T18:27:09Z

W6JMK: add links

An encap.txt file lists [[Gateway|AMPRNet gateways]], in a format like this:

<nowiki># This is a comment
route addprivate 44.10.0.100/32 encap 136.115.52.224
route addprivate 44.100.129.0/24 encap 176.140.10.22</nowiki>

Originally formatted for JNOS systems, it is often parsed with a "[[munge script]]" to update Linux system routing tables.

== Portal ==

To get an encap.txt file that lists all current gateways,
request all routes from the [[API|Portal API]] and convert the response from JSON to text.
For example (using [[API]] version 2):

<nowiki>curl -s -H "Authorization: Bearer $APItoken" -H "Accept: application/json" https://portal.ampr.org/api/v2/encap/routes | jq -r '.encap[] | select(.encapType == "IPIP") | "route addprivate \(.network)/\(.cidr) encap \(.gatewayIP)"'</nowiki>

A more complete example is in [[Encap.txt/get-encap]].

If something goes wrong, the result won't be a complete list.
Before using it to update routing tables, it's worth checking whether it has the right syntax and it's reasonably long.
An empty list or a list that's much shorter than a previous version is probably erroneous.

== HTTP ==

Previously, a complete encap.txt file was available from the portal as a web page.
This is no longer supported.

API

2024-10-15T18:10:50Z

W6JMK: link to json.org

Services

2024-10-15T04:31:29Z

W6JMK: AMPR no longer publishes an encap.txt file.

{| class="wikitable sortable"
|-
! Maintainer !! Service Name!! URL/IP !! Service Type !! Description !! Other Information
|-
| AMPR ||[[Portal]] || https://portal.ampr.org || HTTPS || Used to request allocations, manage user profile information, [[Gateway]] entries and ampr.org DNS entries|| NONE
|-
| AMPR ||Website || https://www.ampr.org || HTTPS || AMPRNet Main Page|| NONE
|-
| AMPR ||Wiki || https://wiki.ampr.org || HTTPS || This Wiki|| NONE
|-
| AMPR ||44Net discussion group || https://ardc.groups.io/g/44net || HTTPS || AMPR discussion group|| NONE
|-
| AMPR ||ARDC announcements || https://ardc.groups.io/g/main || HTTPS || ARDC announcements|| NONE
|-
| AMPR ||AMPRNet Gateway [[Amprgw|(AMPRGW)]] || amprgw.ucsd.edu/169.228.34.84 || IP and IPENCAP [[Tunnel]]|| Routes traffic between the public internet and AMPRNet hosts connected via the IPIP mesh and originates [[RIP]] packets || Gateways use IP Protocol 4 (IPENCAP) to receive traffic via AMPRGW. Allocation must be registered in the [[Portal]] with a ampr.org DNS entry, and gateways must run an AMPRNet routing protocol (i.e. [[RIP]]44 or [[munge script]])
|-
| AMPR ||[[RIP]]44 || provided via [https://en.wikipedia.org/wiki/Broadcasting_%28networking%29 broadcast] from 44.0.0.1 to all [[gateway]]s registered in the [[portal]] || Routing Information (modified RIPv2 protocol) || distributed by main AMPRNet Router to multicast address 224.0.0.9|| 1.) an enabled IPENCAP tunnel, and 2.) [[ampr-ripd]] or [[rip44d]] must be running and properly configured on your registered gateway
|-
| Various Operators||[[Ampr.org]] DNS and Reverse DNS (44.in-addr.arpa) ||
ns.ardc.net 
a.gw4.uk 
ns2.us.ardc.net 
ns1.de.ardc.net 
(These hosts are authoritative for AMPR.ORG and most of the '[0-191].44.in-addr.arpa' reverse zones. 
 
44.0.0.0/9 thru 44.128.0.0/10 hosts may use dns-mdc.ampr.org (44.60.44.3) as a recursive DNS server. It also has a copy of HAMWAN.ORG 
srv.kz2x.ampr.org (44.44.48.29) is a recursive resolver available to 44.0.0.0/9 and 44.128.0.0/10 
|| DNS || name resolution services||
|-
| Various Operators||Network Tools||
http://whatismyip.ampr.org 
http://yo2loj.ampr.org/nettools.php 
http://kb3vwg-010.ampr.org/tools 
http://speedtest.ampr.org 
http://lg.vk7sh.asmpr.org 
|| HTTP|| source IP checker, speed test, Ping, Traceroute, etc.||
'''kb3vwg-010.ampr.org''' only available from hosts with an AMPRNet IP address 
'''lg.vk7sh.asmpr.org''' only available from hosts with an AMPRNet IP address
|-
| Various Operators ||Network Time Protocol || ntp.vk2hff.ampr.org (Stratum 1, AU) time.kz2x.ampr.org (Stratum 1, US) kb3vwg-001.ampr.org (Stratum 2, US) gw-44-137.pi9noz.ampr.org (Stratum 2)|| NTP|| Stratum 2 Network Time Server - References US, Canadian and Mexican|| '''kb3vwg-001.ampr.org''' only available from hosts with an AMPRNet IP address '''time.kz2x.ampr.org''' only available from hosts with an AMPRNet IP address
|-
| N1URO ||AMPRNet/RF faxing || http://wiki.ampr.org/wiki/axMail-FAX || Facsimile || Online IP based Facsimile service. You have the ability to send emergency communications from packet via Fax. || [http://axmail.sourceforge.net axMail-FAX] Sofware is here.
|-
| [http://allstarlink.org AllStar Link] || AllStar || http://allstarlink.org || Linking of repeaters || AllStar Link core network services are provided via redundant datacenters using 44net IP space. || [https://wiki.allstarlink.org/wiki/Main_Page ASL wiki]
|-
| N2NOV and G1FEF || Hub_NA and Hub_EU for WWconvers Chat System || 44.68.41.2:3600 convers.g1fef.co.uk:3600 || Telnet || Only connections from other 44Net addresses allowed using port 3600. Stations like JNOS with a built-in local chat server can link to it. Individuals without a local chat portal can use an IRC client to a public IP address that must be arranged with the owner. || None
|-
| N2NOV || AMPRNet NE US Regional Portal || http://n2nov.ampr.org/hamgate.html || HTTP || AMPRNet NE US Regional Portal || None
|-
| [https://flscg.org/ FSG]|| HamWAN Remote || https://flscg.org/2022/04/hamwan-remote/ || VPN/BGP || We provide a VPN based remote site connection to [https://flscg.org/hamwan/ HamWAN Tampa] and can announce your IP space. Performance of over 1gbit/s is possible and we provide an local connection point for amateurs in the South Eastern United States. || https://wiki.w9cr.net/index.php/HamWAN_Remote_Site
|-
| [https://hamwan.org HamWAN]||HamWAN Open Peering||https://hamwan.org/Labs/Open%20Peering%20Policy.html||BGP/IPSec(AH)||We provide IPsec VPN w/ BGP peering + Internet announcing.||
|-}

Services previously available on AMPRNet but no longer actively supported can be viewed on the [[Services/Historic|Historic Services]] page.

Setting up a gateway on Linux

2024-10-15T04:25:32Z

W6JMK:

There are a few different ways to run an AMPRnet gateway on a Linux system. Each has some benefits, so you'll need to pick your favourite.

Before configuring the Linux gateway you'll need to:
# Using the [[Portal]], request an IP address (or addresses) by clicking on "Request address space" then selecting "IPIP Tunnel Mesh" as the Use Case.
# You will need to have a public static IP address for your gateway.
# Using the [[Portal]], create an entry for your gateway.
# Get some of your AMPRNet IP addresses registered in the [[ampr.org]] DNS.

= Flavours of Linux gateways =

== Native Linux kernel AX.25 and IPIP tunneling ==

Linux contains the necessary building blocks for a gateway without much added software. Radio interfaces are configured much like any other network interfaces such as Ethernet, they're just given amateur radio callsigns in addition to an IP address (callsign will act the role of the Ethernet MAC address). If you're familiar with Linux configuration but have not heard of NOS, or if you wish to go with minimal amount of moving parts, this would probably be your choice.

Setting up a native Linux gateway consists of two main steps:

=== Step 1: Setting up tunnel routing to the rest of the AMPRnet===
Configuring your Linux system to learn about other AMPRNet [[gateway| gateways]] can be done two ways:

# Automatically learn about other gateways via modified RIPv2 advertisements. Two popular programs to do this are:
## Using [[ampr-ripd]], a C based routing daemon
## Using [[rip44d]], a PERL based routing daemon
# Downloading an [[encap.txt]] file and setting up routes using a [[munge script]] is the traditional method

====Example Gateway Configuration Instructions====
* [[Ubuntu Linux Gateway Example]]
* [http://www.qsl.net/k/kb9mwr//wapr/tcpip/ampr-ripd.html Two Interface Debian Linux Amprnet Gateway Example]
* [https://k7ilo.blogspot.com/p/server-setup.html K7ILO'S Two Interface Debian 11 AmprNet Gateway Build in layman's terms]

=== Step 2: Setting up radio interfaces in Linux===

* [http://www.tldp.org/HOWTO/AX25-HOWTO/ Linux AX.25 set-up]
* 802.11 WiFi on amateur frequencies (2.4 or 5 GHz) is a new popular way to set up fast links.

== Running JNOS (or other NOS) on top of Linux ==

If you're already familiar with running NOS on top of DOS or Linux, or wish to keep the AMPRnet IP packet routing away from the host Linux system, it might make sense to run JNOS as an application on top of Linux.

The downside is that it'll have a slightly higher overhead (consumed memory and CPU), and you'll have two IP routers running on top of each other instead of just one, which is seen as slightly complicated by some.

The upside is that you'll also get the JNOS BBS-type features, and some other traditional services without installing additional software on top.

=See also=

* [[Ubuntu Linux Gateway Example]]
* [[startampr]]

RIP

2024-10-15T04:22:55Z

W6JMK:

Information about other AMPRNet [[gateway| gateways]] can now be received dynamically via modified [http://en.wikipedia.org/wiki/Routing_Information_Protocol#RIP_version_2 RIPv2] advertisements.
Routes can also be downloaded as an [[Encap.txt|encap.txt]] file.

= What's the difference? =

There is a big difference from RIPv2 in how the packets are processed.

The regular RIPv2 sets a route to a specific subnet via the sender and
interface where the RIP broadcast was received on. The gateway
information is used only as an optimization element, in case a route
with to that gateway already exists so that the one with the lower
metric gets chosen.

In our case, we use the RIP announcements to transport the subnet AND
gateway information.

= Detailed description =

So, assuming a point to multipoint interface, if there is let's say an
announcement 44.128.0.0/24 via 1.2.3.4 coming from 44.0.0.1 on the ipip0
interface, regular RIPv2 would translate this to:

44.128.0.0/24 via 44.0.0.1 if ipip0

while ampr rip would translate this to:

44.128.0.0/24 via 1.2.3.4 if ipip0

In the first case, traffic to 44.128.0.0/24 is sent directly to the
gateway (the RIP sender), while in the second case it is encapsulated to
1.2.3.4.

On a mikrotik router it even goes a step further:
it creates a ipip tunnel interface, ampr-1.2.3.4 to 1.2.3.4 and creates
a route

44.128.0.0/24 via ampr-1.2.3.4

This is the processing in the usual case, for 44 subnets having a 44net
gateway we assume that the gateway is published by BGP and is directly
reachable, so for a announcement like 44.128.0.0/24 via 44.128.0.1 there
are 2 route set:

44.128.0.1 via default-gw (which is autodetected), and
44.128.0.0/24 via 44.128.0.1 if ipip0 to do the encapsulation

So, while the information structure in both cases conforms to the RIPv2
specifications, its usage is completely different.

= RIP44 Daemons =

Two programs are available for GNU/Linux to utilize these updates:

* [[ampr-ripd]], a C based routing daemon
* [[rip44d]], a PERL based routing daemon

A program is also available for [https://www.openbsd.org/ OpenBSD]:

* [https://github.com/dancrossnyc/44ripd 44ripd]

= Availability/Compatibility =

The RIP44 daemons have been tested and known to work on the following operating systems:

* BSD
* OpenWRT/LEDE
* Raspbian
* Slackware Linux
* Ubuntu/Debian Linux
* Vyatta/VyOS

= Non-RIP44 Workarounds =

The devices below do not possess a known, end-user method to install additional software (i.e. ampr-ripd). Operators have developed scripts to parse inbound routing packets to make them compatible for usage on AMPRNet:

* Cisco IOS (a separate machine must run the script) : look here http://wiki.ampr.org/wiki/Setting_up_a_gateway_on_Cisco_Routers at the "Making the route commands automatically" section
* JunOS
* MikroTik : look here http://www.yo2loj.ro/hamprojects/ at the "Mikrotik RIPv2 AMPR Gateway Setup Script 3.0"
* Ubiquiti OS

= See Also =

* [[startampr]] - a script that loads the routing daemon on boot on Linux server-type devices
* Instructions for [[setting up a gateway on Linux|setting up a tunnel gateway on Linux]]
* Instructions for [[setting up a gateway on OpenWRT|setting up a gateway on OpenWRT]]
* Instructions for [[setting up a gateway on OpenBSD|setting up a gateway on OpenBSD]]

Gateway

2024-10-15T04:16:22Z

W6JMK:

Much of the AMPRNet address space is interconnected via [[gateway|gateways]] that implement IPENCAP ([http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml IP Protocol Number 4]) encapsulated [[tunnel|tunnels]]. These tunnels provide endpoints for the AMPRNet address space allocated to a particular region or end user, effectively forming a mesh network of interconnected tunnels between AMPR subnets.
The [[portal]] maintains a database of all the gateways, their public IP addresses, and the subnets they serve.
This routing information is distributed via modified [[RIP]] advertisements.
A complete list of gateways can be downloaded from the [[API|portal API]].

In order to keep this database up to date, everyone that operates a gateway must register on the [[portal]] and have their gateway(s) assigned to their account and associated with their allocation(s).

In addition to the gateways operated by users who connect via IPENCAP tunnels, traffic exchanged between the ARMPNet mesh and the public Internet is routed via the [[Amprgw]] – please see the [[Amprgw]] page for important details on passing traffic between the public Internet and the IPENCAP tunnel mesh.

Learn how to [[Setting up a gateway on Cisco Routers|set up a Cisco Router gateway]]

Learn how to [[Setting up a gateway on Linux|set up a Linux gateway]]

Learn how to [[setting up a gateway on MikroTik Routers|set up a gateway on MikroTik Routers]]

Learn how to [[Setting up a gateway on OpenBSD|set up an OpenBSD gateway]]

Learn how to [[Setting up a gateway on OpenWRT|set up an OpenWRT gateway]]

Encap.txt

2024-10-15T03:08:57Z

W6JMK: Recommend validating a response from the API.

An encap.txt file lists AMPRNet [[gateway| gateways]], in a format like this:

<nowiki># This is a comment
route addprivate 44.10.0.100/32 encap 136.115.52.224
route addprivate 44.100.129.0/24 encap 176.140.10.22</nowiki>

Originally formatted for JNOS systems, it is often parsed with a "[[munge script]]" to update Linux system routing tables.

== Portal ==

To get an encap.txt file that lists all current gateways,
request all routes from the [[API]] and convert the response from JSON to text.
For example (using API version 2):

<nowiki>curl -s -H "Authorization: Bearer $APItoken" -H "Accept: application/json" https://portal.ampr.org/api/v2/encap/routes | jq -r '.encap[] | select(.encapType == "IPIP") | "route addprivate \(.network)/\(.cidr) encap \(.gatewayIP)"'</nowiki>

A more complete example is in [[encap.txt/get-encap]].

If something goes wrong, the result won't be a complete list.
Before using it to update routing tables, it's worth checking whether it has the right syntax and it's reasonably long.
An empty list or a list that's much shorter than a previous version is probably erroneous.

== HTTP ==

Previously, a complete encap.txt file was available from the portal as a web page.
This is no longer supported.

Encap.txt/get-encap

2024-10-15T02:53:36Z

W6JMK: Created page with "Here's a bash script to get a complete encap.txt file from the portal. For example: .\get-encap < api-token.txt > encap.txt || echo error $? The script maintains a cache, so it downloads the information only when it has changed. <nowiki> #!/bin/bash # Output the current AMPRNet routing information, like this: # # Fetched <when> version <number> from <source> # route addprivate 44.0.1.0/32 encap 169.228.84.34 # route addprivate 44.102.240.16/28 encap 45.145.74.24..."

Here's a bash script to get a complete [[encap.txt]] file from the portal.
For example:

.\get-encap < api-token.txt > encap.txt || echo error $?

The script maintains a cache, so it downloads the information only when it has changed.

<nowiki>
#!/bin/bash
# Output the current AMPRNet routing information, like this:
# # Fetched <when> version <number> from <source>
# route addprivate 44.0.1.0/32 encap 169.228.84.34
# route addprivate 44.102.240.16/28 encap 45.145.74.247
# ...

cache="${1:-routes.json}" # a file that stores previous information
token=`cat -` # an API token
# To obtain a token, register with http://portal.ampr.org/ , log in,
# browse your profile and copy the value of "API Token".
# Be sure to keep the token private. This script won't reveal it.

API="https://portal.ampr.org/api/v2"
# The API returns JSON, something like:
# {
# "count": 836,
# "serial": "136.269",
# "encap": [
# {
# "gatewayIP": "118.82.153.200",
# "encapType": "IPIP",
# "network": "44.147.0.210",
# "cidr": 25,
# ...
# },
# ...
# ]
# }
# ... but without any insignificant white space.
# We trust that any change will also change the serial value.

allZero () {
for status in "$@"; do
[ "$status" != 0 ] && return "$status"
done
return 0
}

curlOptions="-H \"Authorization: Bearer $token\"
-H \"Accept: application/json\"
"
if [[ -e "$cache" && ! -f "$cache" ]]; then
echo >&2 `basename "$0"`": $cache isn't a regular file."
exit 1
elif [ -r "$cache" ]; then
oldVersion=`jq ".serial" "$cache"` || oldVersion="cache error $?"
[ "$oldVersion" == "null" ] && oldVersion="N/A" # != $newVersion
newVersion=$(
echo "$curlOptions" | curl -s --config - "$API"/encap/serial | jq ".serial"
allZero "${PIPESTATUS[@]}" || exit $?
) || newVersion="API error $?"
else
oldVersion="N/A" # != $newVersion
newVersion="TBD"
fi
# echo "# oldVersion=$oldVersion newVersion=$newVersion"
if [ "$newVersion" != "$oldVersion" ]; then
# Fetch new data from the API and store it in $cache:
newVersion=$(
echo "$curlOptions" | curl -s --config - "$API"/encap/routes | tee "$cache" | jq ".serial"
allZero "${PIPESTATUS[@]}" || exit $?
) || exit $?
fi
# Convert $cache to the output format:
echo "# Fetched" `date -r "$cache"` version "$newVersion" from "$API" || exit $?
jq -r '.encap[] | select(.encapType == "IPIP") | "route addprivate \(.network)/\(.cidr) encap \(.gatewayIP)"'\
"$cache" | sort
# Sorting the output makes it easier to compare different versions.
allZero "${PIPESTATUS[@]}" || exit $?
</nowiki>

Encap.txt

2024-10-15T01:38:47Z

W6JMK: Use the API to get all routes. The portal doesn't provide an encap.txt file via HTTP.

An encap.txt file lists AMPRNet [[gateway| gateways]], in a format like this:

<nowiki># This is a comment
route addprivate 44.10.0.100/32 encap 136.115.52.224
route addprivate 44.100.129.0/24 encap 176.140.10.22</nowiki>

Originally formatted for JNOS systems, it is often parsed with a "[[munge script]]" to update Linux system routing tables.

== Portal ==

To get an encap.txt file that lists all current gateways,
request all routes from the [[API]] and convert the response from JSON to text.
For example (using API version 2):

<nowiki>curl -s -H "Authorization: Bearer $APItoken" -H "Accept: application/json" https://portal.ampr.org/api/v2/encap/routes | jq -r '.encap[] | select(.encapType == "IPIP") | "route addprivate \(.network)/\(.cidr) encap \(.gatewayIP)"'</nowiki>

== HTTP ==

Previously, a complete encap.txt file was available from the portal as a web page.
This is no longer supported.

API

2024-10-15T01:12:13Z

W6JMK: Don't show API URLs as links.

The AMPRNet [[Portal]] has an associated API that allows the data and functionality of the [[Portal]] to be accessed programatically.

=== Version 1 ===

Version 1 of the API uses a RESTful design, accessible only via SSL (https://) to increase security.

All requests to the API require the client to authenticate by using Basic HTTP authentication,
so you will need a username and password in order to access any part of the API,
this can be obtained by registering for an account on the [[Portal]].

Once you have an account, you can create your API Key (password) from the "Profile' menu link, in the "Security" section.
The API username is the same username you used to login to the [[Portal]] via your web browser.

=== Version 2 ===

Version 2 of the API also uses a RESTful design. Requests and responses are exchanged via HTTPS.
Access is controlled using [https://datatracker.ietf.org/doc/html/rfc6750 Bearer authorization].
So, each request must include an HTTP header like this:

Authorization: Bearer <API Token>

To obtain an API token, register with the [[Portal]], log in,
browse your profile and copy the value of "API Token".

Some responses are in JSON format. Requests should include a header:

Accept: application/json

To get complete current routing information in JSON,
request <nowiki>https://portal.ampr.org/api/v2/encap/routes</nowiki>.
For example, a Unix command like this will output complete current routing information:

curl -s -H "Authorization: Bearer $APItoken" -H "Accept: application/json" <nowiki>https://portal.ampr.org/api/v2/encap/routes</nowiki>

The response includes a serial number, which changes when any route is updated.
To get the current serial number (but not the routes) in JSON,
request <nowiki>https://portal.ampr.org/api/v2/encap/serial</nowiki>.

API

2024-10-15T00:51:37Z

W6JMK: Document the API version 2. I can't find any documentation of API version 1, nor any API documentation in https://portal.ampr.org .

The AMPRNet [[Portal]] has an associated API that allows the data and functionality of the [[Portal]] to be accessed programatically.

=== Version 1 ===

Version 1 of the API uses a RESTful design, accessible only via SSL (https://) to increase security.

All requests to the API require the client to authenticate by using Basic HTTP authentication,
so you will need a username and password in order to access any part of the API,
this can be obtained by registering for an account on the [[Portal]].

Once you have an account, you can create your API Key (password) from the "Profile' menu link, in the "Security" section.
The API username is the same username you used to login to the [[Portal]] via your web browser.

=== Version 2 ===

Version 2 of the API also uses a RESTful design. Requests and responses are exchanged via HTTPS.
Access is controlled using [https://datatracker.ietf.org/doc/html/rfc6750 Bearer authorization].
So, each request must include an HTTP header like this:

Authorization: Bearer <API Token>

To obtain an API token, register with the [[Portal]], log in,
browse your profile and copy the value of "API Token".

Some responses are in JSON format. Requests should include a header:

Accept: application/json

To get complete current routing information in JSON,
request https://portal.ampr.org/api/v2/encap/routes .
The response contains a serial number, which changes when any route is updated.
To get the current serial number (but not the routes) in JSON,
request https://portal.ampr.org/api/v2/encap/serial .

For example, a Unix command like this will output complete current routing information:

curl -s -H "Authorization: Bearer $APItoken" -H "Accept: application/json" https://portal.ampr.org/api/v2/encap/routes