Using the custom-webserver-page commands

You can use the custom-webserver-page commands to customize the web server error pages on your Developer Portal service.

The custom-webserver-page commands enable you to set, get, and delete custom HTML content for the web server error pages of index, 404, 40x, and 50x. You can embed base64 encoded images, such as .svg and .png, or inline .svg images in your content, but the maximum size of the content of each error page is 8 MB.
Note:
  • The custom web server error pages that can be set by using the custom-webserver-page commands, are the pages that are returned when the URL of a specific portal site isn't used. For example, if your portal site was https://example.com/myorg/dev, but you went to https://example.com/myorg/deb, then this is when a custom 404 error page is returned. However, if the requested URL matches a portal site, then the web server will use the Drupal error handlers, and will respond according to the Drupal configuration.
  • All custom content that you set must conform to the HTML5 specification. If you try to set custom content that doesn't conform to HTML5, it will fail with the following error message:
    Error: The supplied custom HTML failed validation.
  • Setting and deleting custom web server pages can take several minutes to complete, depending on the size of the content.
  1. Log in as Cloud manager: 
    apic login --server management_server --realm admin/identity_provider --username admin --password cloud_password
    You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):
    apic identity-providers:list --scope admin --server mgmt_endpoint_url --fields title,realm
    For example:
    apic identity-providers:list --scope admin --server myserver.com --fields title,realm
total_results: 2
results:
  - title: Cloud Manager User Registry
    realm: admin/default-idp-1
  - title: Corporate LDAP user registry
    realm: admin/corporate-ldap
    The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default Cloud Manager Local User Registry for login as a member of the cloud administration organization is default-idp-1.

    For full details of the apic login command, see Logging in to a management server.

  2. Set a custom HTML web server error page on the Developer Portal. The maximum size of the page is 8 MB, and you must ensure that the content conforms to the HTML5 specification, or the custom-webserver-page:set command will fail with a validation error.
    apic --mode portaladmin custom-webserver-page:set --server management_server --portal_service_name portal --page_type page_type filename.html
    • management_server is the endpoint URL of the management server (required).
    • portal is the name of the portal service (required).
    • page_type is the type of web server error page that you want to run the command against (required). Valid values are index, 404, 40x, or 50x.
    • filename is the name of the HTML file that contains the content for the custom web server error page.

    For example, the following screen capture shows a standard 404 web server response:

    Screen capture of a standard web server 404 Not Found error message.
    Then the following custom-webserver-page:set command is run:
    apic --mode portaladmin custom-webserver-page:set --server my.management.server.com --portal_service_name portal --page_type 404 custom-404.html
Loading File (Large files may take a while)...

Successfully added the custom HTML content for page type 404.

    The following custom 404 error page is now displayed:

    Screen capture of a custom 404 error page, showing a picture of a person looking at a map, and with the words Error 404 Hmm, we can't seem to find that.
  3. Get the custom content of a specific page type and save it to a file named <page_type>-timestamp.html.
    apic --mode portaladmin custom-webserver-page:get --server management_server --portal_service_name portal --page_type page_type
    For example:
    apic --mode portaladmin custom-webserver-page:get --server my.management.server.com --portal_service_name portal --page_type 404
Incoming project saved to 404-20211027121830.html
    If there is no custom content available for the page type, the following error is displayed:
    apic --mode portaladmin custom-webserver-page:get --server my.management.server.com --portal_service_name portal --page_type 50x
Error: There is currently no custom HTML content for page type 50x.
  4. Delete the custom content of a specific page type. If there is no custom content available for a page type, the error response defaults to the standard web server error page.
    apic --mode portaladmin custom-webserver-page:delete --server management_server --portal_service_name portal --page_type page_type
    For example:
    apic --mode portaladmin custom-webserver-page:delete --server my.management.server.com --portal_service_name portal --page_type 404
The custom HTML content for page type 404 has been deleted.