This article is a brief overview of licensing, setup, configuration, promoting, and disconnecting a secondary Lighthouse instance. For more information including upgrading and CLI options, consult the latest Lighthouse User Manual.
Note: Mixed Hosting environments are not supported at this time. Each Lighthouse instance must be hosted in a matching environment. i.e. - if using Azure you must host Primary and Secondary in Azure.
To use the multiple instance feature, you must install a license that supports this feature on the primary Lighthouse instance.
Setting up multiple instance
- Start two Lighthouse instances, each with a version of Lighthouse that supports multiple instance
(5.3.0 or later).
- Configure the networking information for each instance (hostname, external endpoints, network addresses).
- Configure time settings of each instance.
- Install a license with the multiple instance feature on the primary Lighthouse.
- On the primary Lighthouse, click Configure > Multiple Instance > Dependent Lighthouse Instances.
- Click Add. Enter the network address, username and password of Lighthouse instance to enroll as secondary.
- Please note, the secondary Lighthouse instance must be able to reach the primary instance on UDP Port 1195
- Dependent Lighthouse enrollment will show status as is moves from Pending > Registered > Enrolled.
Multiple instance configuration
Lighthouse with multiple instance support requires multiple separate subnets for Lighthouse VPN
connections: between each instance and its nodes, and between the primary and dependent Lighthouses. Each subnet must not overlap any subnet in use by another Lighthouse instance.
The subnet between the primary Lighthouse and its nodes is modified under Settings > Services > Lighthouse VPN on the primary Lighthouse. Click the button under Actions to calculate the addressable nodes based on the network address and CIDR mask.
A secondary Lighthouse is read-only and cannot be modified. The Settings > Services > Lighthouse VPN page displays the subnet used by this Lighthouse instance, but it cannot be modified directly.
The subnet between each secondary Lighthouse and its nodes can be modified on the primary
Lighthouse under Configure > Multiple Instance > Dependent Lighthouse Instances > Edit.
The subnet between the primary Lighthouse and dependent Lighthouse instance can be modified on the primary Lighthouse under Configure > Multiple Instance > Lighthouse VPN
Other information that is specific to dependent Lighthouse should be configured before enrolling but can be modified on the primary Lighthouse via ogconfig-cli. Instance specific information includes:
- time zone
- external interfaces
Lighthouse Multiple Instance and Alternate REST API Port
If you are planning to use the alternate REST API ports, you will need to make sure this option is enabled on both the primary and dependent Lighthouse servers, prior to enrollment of the dependent(s). Lighthouse will prevent the enrollment of a dependent Lighthouse instance if there is a mismatch in these settings. If this occurs, the message "Lighthouse is using Alternate API port" will be displayed on the Dependent Lighthouse Instances page.
To fix the issue, either
- enable the Alternate REST API port on both Lighthouse servers, or
- disable the Alternate REST API port on both Lighthouse servers, then delete the failed Lighthouse enrollment and try again.
The Alternate REST API Port is configured through the web UI in Settings > Services > Session Settings page.
Disconnecting a secondary instance
Dependent Lighthouse instances can be removed from the primary Lighthouse. Click Configure
> Multiple Instance > Dependent Lighthouse Instances, and click the x button under Actions next to the instance.
The secondary Lighthouse will begin unenrollment, which will factory reset the secondary Lighthouse. A user will be required to enter a new root password via console when it reboots.
You will need to manually remove the connection to the secondary Lighthouse from each connected node. Clean dead connections from node side by clicking the Delete link in the Console Server.
Promoting a secondary instance
When a primary Lighthouse is no longer reachable, a secondary Lighthouse instance can be promoted to primary. The new primary can then be used to enroll a secondary Lighthouse if required.
NOTE: This should only be performed if the primary Lighthouse has no chance of returning, the procedure is not reversible and will break all node connections with the previous primary instance. The previous primary instance must be factory reset before it can be used again.
To promote a secondary instance to primary, login as root on the secondary instance via console or ssh and run promote-secondary-lighthouse.
You will need to remove all dead connections from node side from the Console Server. The new primary can then be used to enroll a secondary Lighthouse.
NOTE: If the previous primary becomes accessible again, it will not be able to connect to its enrolled nodes or the previous secondary Lighthouses.