Advanced Use Cases

Over time Majora has been adapted to many customer scenarios. Most deployments do not need heavy customization, so this chapter documents how to address the more advanced requests.

Starting with Majora v3, IP pool concepts are first-class citizens, so the configuration described here builds on top of the pool/endpoint mapping that already exists in the product.

Not every requirement should turn into a core feature—adding concepts for one customer often increases cognitive load for everyone else. If you need highly tailored behavior, consider licensing the source code for in-house customization.

Secondary Development

Many teams treat Majora as an infrastructure layer and build business logic around it. All REST APIs are documented via Swagger:

• The official frontend is built entirely on these APIs. If you want to retain the core while creating a custom skin, you can re-implement the UI against the same endpoints.
• Deploy your compiled frontend under conf/static/ to ship it with the server.

API Reference

API Conventions

• AdminOnly: the endpoint can only be called by administrators.
• SupportApiToken: the endpoint accepts the user’s API token.

Endpoints without these flags are public. The API token is shown in the user profile; it is stable so you can embed it in code.

Webhooks

Subscribe to real-time events (for example device online/offline) with webhooks:

def DD_WEBHOOK = "https://oapi.dingtalk.com/robot/send?access_token=xxxxToken"

endpointOffline {
    def json = new JsonBuilder()
    json {
        msgtype "text"
        text {
            content "Endpoint offline: clientId=${clientId}, group=${group}"
        }
    }
    asyncPost DD_WEBHOOK, json
}

endpointOnline {
    def json = new JsonBuilder()
    json {
        msgtype "text"
        text {
            content "Endpoint online: clientId=${clientId}, group=${group}"
        }
    }
    asyncPost DD_WEBHOOK, json
}

Use asyncPost when thousands of nodes are involved to avoid blocking on HTTP calls.

Whitelist Authentication

Majora supports username/password and IP whitelist authentication. Whitelists are useful when the client cannot present credentials, but the exit IP may change (for example broadband or mobile networks).

• Use the HTTP API to add/remove whitelist entries dynamically.
• The API captures the caller’s source IP automatically; no need to query external services.
• Requests are protected by the API token.
• Majora retains entries using an LRU strategy, removing stale IPs when the capacity limit is reached.

This approach may lead to brief downtime (minutes) while the whitelist refreshes, but it works well for most scenarios.

System Settings

The admin console exposes several important switches:

User Registration

If Majora is exposed to the public Internet, disable self-registration to prevent unauthorized access.

Swagger & Actuator

Some corporate firewalls flag open API docs as data leaks. You can disable the Swagger UI and Spring Actuator endpoints to avoid alarms.

Access Control Lists

Block access to certain hosts or IP ranges to comply with local regulations:

all:*.baidu.com,*.google.com,www.tencent.com,114.54.34.23,123.434.*;some-user1:*.google.com;some-user2:*.gov.cn

• Entries are separated by ;.
• all applies to every user.
• Wildcards support domains (*.baidu.com) and IP segments (123.434.*).
• ACLs are deny rules—matching traffic is blocked.

SSL over SSL (Planned)

HTTPS proxying already tunnels TLS traffic end-to-end. If you also want the connection between the client and Majora to be encrypted (HTTPS over HTTPS), you must configure an HTTPS certificate on the Majora server.

Steps:

1. Obtain a CA-issued certificate.
2. Mount the certificate into the container if you use Docker.
3. Configure application.properties:

   server.ssl.keyStore=/path/to/ssl_key_store_file.pfx
   server.ssl.keyStoreType=PKCS12
   server.ssl.keyStorePassword=your_password

4. Restart Majora and use proxy URLs like https://majora:majora@majora3.iinti.cn:6879.

Majora can also generate self-signed certificates, but clients must install the root CA. This niche scenario is rarely needed and not covered further here.