How to Use the Command `gitlab-ctl` (with Examples)

gitlab-ctl is a command-line utility provided by GitLab that allows users to manage an omnibus GitLab installation. This command is used for controlling various GitLab services, checking their statuses, restarting them, and viewing their logs. It helps system administrators to efficiently administer the GitLab instance without requiring extensive manual intervention, ensuring consistent and reliable operations.

Use Case 1: Display the Status of Every Service

Code:

sudo gitlab-ctl status

Motivation:

Understanding the current status of every service running on your GitLab instance is crucial for maintaining operational efficiency and troubleshooting. By executing this command, you can get a comprehensive overview of which services are running smoothly and which might need attention, especially after a recent configuration change or update.

Explanation:

• sudo: This command requires superuser (administrator) privileges because it interacts with system-level services.
• gitlab-ctl: The core command used to manage GitLab omnibus services.
• status: A subcommand that requests the current status of every service associated with GitLab.

Example Output:

run: gitlab-workhorse: (pid 1234) 123s; run: log: (pid 2345) 456s
run: nginx: (pid 3456) 789s; run: log: (pid 4567) 901s
run: redis: (pid 5678) 234s; run: log: (pid 6789) 345s
...

This output lists each service by name, its process ID (PID), and the duration it has been running, which helps quickly identify any inactive services.

Use Case 2: Display the Status of a Specific Service

Code:

sudo gitlab-ctl status nginx

Motivation:

When troubleshooting or configuring a specific service, such as nginx in this case, it’s often necessary to check its status independently. This allows for a focused approach to diagnosing and addressing issues with the particular service without the clutter of unrelated service information.

Explanation:

• sudo: Elevated privileges are needed to access system services.
• gitlab-ctl: Manages the GitLab services.
• status: The subcommand for checking the status.
• nginx: Specifies that this command should return the status of the nginx service specifically.

Example Output:

run: nginx: (pid 6789) 150s; run: log: (pid 7890) 300s

This confirms whether nginx is running and provides insights such as its process IDs and uptime duration.

Use Case 3: Restart Every Service

Code:

sudo gitlab-ctl restart

Motivation:

Restarting all services can be necessary after applying updates, configurations, or when troubleshooting inter-service issues. This ensures all components of GitLab are reloaded and synchronized, applying any recent changes across the board.

Explanation:

• sudo: Superuser access is required.
• gitlab-ctl: Core command for managing GitLab services.
• restart: Subcommand used to stop and then start services again, affecting all services.

Example Output:

ok: run: gitlab-workhorse: (pid 1234) 0s
ok: run: nginx: (pid 2345) 0s
ok: run: redis: (pid 3456) 0s
...

The output shows successful restarts of each service with new process IDs and indicates everything is back to a running state.

Use Case 4: Restart a Specific Service

Code:

sudo gitlab-ctl restart nginx

Motivation:

In some situations, only a single service requires a restart, such as when only nginx configuration changes are made or if the service is experiencing issues. Restarting just one service can be more efficient and less disruptive.

Explanation:

• sudo: Allows the execution of administrative commands.
• gitlab-ctl: The command to control GitLab services.
• restart: Initiates a stop and start sequence.
• nginx: Signifies that the nginx service alone should be restarted.

Example Output:

ok: run: nginx: (pid 8901) 0s

This confirms that the nginx service has been successfully restarted with a new PID, without affecting other services.

Use Case 5: Display the Logs of Every Service and Keep Reading

Code:

sudo gitlab-ctl tail

Motivation:

Monitoring logs in real-time is crucial for catching ongoing issues as they occur. Viewing logs of all services continuously helps in diagnosing widespread problems affecting your GitLab instance.

Explanation:

• sudo: Needed for accessing log files with administrative privileges.
• gitlab-ctl: Manages the services.
• tail: Continuously outputs the log content, updating in real time.

Example Output:

==> /var/log/gitlab/nginx/current <==
2023-01-01_12:34:56.78900 INFO Request started GET /login ...

==> /var/log/gitlab/gitlab-workhorse/current <==
2023-01-01_12:34:57.78901 INFO Processing by SessionsController#create ...

The terminal continually updates with logs from all services, useful for diagnosing widespread issues.

Use Case 6: Display the Logs of a Specific Service

Code:

sudo gitlab-ctl tail nginx

Motivation:

Focusing on the logs of a specific service like nginx helps in pinpointing issues related directly to that service. This is particularly useful when investigating a service-specific problem or validating changes made to its configuration.

Explanation:

• sudo: Needed for access to the service’s log files.
• gitlab-ctl: Used for managing GitLab services.
• tail: The command for viewing continuous log updates.
• nginx: Specifies that it should only show logs from the nginx service.

Example Output:

==> /var/log/gitlab/nginx/current <==
2023-01-01_12:35:00.78902 INFO Request method GET completed
2023-01-01_12:35:05.78904 INFO Successful GET /api/users ...

The output displays live log data from nginx, allowing administrators to quickly identify and address issues specific to that service.

Conclusion

The gitlab-ctl command is a powerful tool for managing a GitLab omnibus installation, offering precise control over services through various commands. By understanding how to use these commands, administrators can ensure the reliability and efficiency of their GitLab instances. Each use case addresses different aspects of service management, from monitoring and restarting services to viewing detailed logs, providing comprehensive capabilities for maintaining a robust and stable development environment.