Installation

1. Install using PIP.

pip install django-portmaster

2. Add app to your Django project’s settings file and include offer cleanup middleware.

INSTALLED_APPS = [
    [..]
    'django_portmaster'
]

MIDDLEWARE = [
    [..]
    'django_portmaster.middleware.CleanOldOffersMiddleware'
]

3. Include Portmaster’s URLs into your Django project’s urls file.

from django_portmaster.urls import portmaster_urlpatterns
urlpatterns += portmaster_urlpatterns

4. Optionally, you can override the time offers are kept before they are deleted. Add the following code to you settings.py file.

# Default value is 30 minutes
PM_DELETE_OFFERS_AFTER_MINUTES = 10

API

• Define port range by creating a service.

POST /v1/services

{
   "name": "django",
   "description": "Django service",
   "start": 5000,
   "end": 10000
}

• Request a port from the range by providing a service instance name.

POST /v1/services/django/offers

{
    "name": "web-01"
}

Response

{
    "service": "django",
    "name": "web-01",
    "port": 5000,
    "secret": "6f8ffc86-d98a-49ba-848a-a7cbaaea9360",
    "created": "2017-09-08T14:16:39.277408Z"
}

• Port will not be allocated immediately. Instead it will be reserved until the client accepts the port by posting to the dedicated URL using the provided secret code:

POST /v1/services/django/offers/6f8ffc86-d98a-49ba-848a-a7cbaaea9360/accept

Response

{
    "service": "django",
    "name": "web-01",
    "port": 5000,
    "created": "2017-09-08T14:18:04.094357Z"
}

• Alternatively, you can reject the offer. Offers that are not accepted are automatically deleted by Portmaster middleware after they reach threshold set by PM_DELETE_OFFERS_AFTER_MINUTES setting (default value is 30 minutes).

POST /v1/services/django/offers/6f8ffc86-d98a-49ba-848a-a7cbaaea9360/reject

• You can list all port alocations for a particular service.

GET /v1/services/django/ports

• Find one by port number

GET /v1/services/django/ports/5000

• Or find one by service instance name

GET /v1/services/django/ports/web-01

Safe guards

Portmaster includes multiple error checks and corner case handlers, so:

• Service name needs to be unique

• Port ranges can not overlap

• Port range can not overlap with privileged ports (<1024) or IANA defined ephemeral port range (>49152)

• Port can be assigned only once at any given time

• Service instance name needs to be unique