greenarrow Command
- Table of Contents
- Introduction
- General Info
- Configuration Management
- Disk Usage
- Disk Queue Messages
- Disk Queue Summary
- GreenArrow Update
- Paused Domains
- Service Management
Introduction
The command greenarrow is a central command for accessing various command-line
functionalities of GreenArrow. Our goal is for it to be the single way to interact
with GreenArrow on the command-line, but we’re not quite there yet.
This page describes some of the functions that the greenarrow command provides.
General Info
The command greenarrow info will print some key information about your installation
of GreenArrow.
$ greenarrow info
GreenArrow Version: v4.282.0 (2023-04-27)
Persistence Mode: Traditional
License Key: (not shown)
License Key: Status: current
License Key: Expiration: None; Perpetual License
License Key: Updates Expiration: 2024-06-01; only licensed to run versions of GreenArrow released on or before this date
This command provides a --json option to get this information as a JSON document.
$ greenarrow info --json
{
"version": "v4.282.0",
"version_date": "2023-04-27",
"persistence_mode": "Traditional",
"persistence_path": "",
"license_key": "(not shown)",
"license_key_expiration_date": "",
"license_key_updates_expiration_date": "2024-06-01",
"license_key_status": "current"
}
On a real system, the license key will be shown in the above commands. We’ve simply hidden it here.
Configuration Management
The command greenarrow config validate is used to check that GreenArrow’s configuration files are valid
and warn about any potentially problematic situations.
greenarrow: Usage:
greenarrow config validate [ARGUMENTS]
Validate current GreenArrow configuration.
Help Options:
-h, --help Show this help message
After editing GreenArrow configuration, most changes are applied using the greenarrow config reload command.
Some changes require additional commands, which are documented where that configuration is described.
greenarrow: Usage:
greenarrow config reload [ARGUMENTS]
Reload current GreenArrow configuration.
Help Options:
-h, --help Show this help message
GreenArrow performs best when its system is configured in certain ways. The command greenarrow config recommend_sysctl
will look for a few particular sysctl settings and recommend tuning.
greenarrow: Usage:
greenarrow config recommend_sysctl [OPTIONS]
Recommend Linux sysctl settings for the current configuration.
Help Options:
-h, --help Show this help message
Disk Usage
See this page for documentation on the greenarrow disk_usage command.
Disk Queue Messages
See this page for documentation on the greenarrow report print_disk_queue command.
Disk Queue Summary
The command greenarrow report disk_queue_summary prints to the terminal the same information
as provided by the Disk Queue Summary API.
greenarrow: Usage:
greenarrow report disk_queue_summary [OPTIONS]
Print a summary of the contents of the disk queue.
Application Options:
--json print a JSON document containing this report
--group-by= group by: virtualmta_injected, virtualmta_most_recent (default:
virtualmta_injected)
--group-variant= group variant: none, recipient_domain, all_throttles,
all_throttles_other, only_explicit_throttles,
not_explicit_throttles (default: none)
--sort-by= sort by: num_messages_desc, num_messages_asc, avg_age_desc,
avg_age_asc, max_age_desc, max_age_asc (default: num_messages_desc)
--limit= limit the number of entries returned (default: 100)
Help Options:
-h, --help Show this help message
See the Disk Queue Summary API for more detailed information on the available options and output format.
GreenArrow Update
The command greenarrow update executes the automatic updates to the current system after the
GreenArrow packages have been upgraded.
This command does not upgrade those packages – it is instead responsible for running database migrations and other automatic update procedures after the packages have been upgraded.
In versions of GreenArrow prior to v4.304.0, hvmail_migrate migrate was the command to execute
these procedures. While that command is still supported, greenarrow update is the preferred command.
Paused Domains
See Pausing Domains for more information.
List Paused Domains
The command greenarrow report paused_domains will list the domains that are currently paused.
The report includes the following columns:
| Began At |
The time the pause went into effect (in engine_time_zone). |
| Ends At |
The time the pause will end (in engine_time_zone). |
| Source Domain |
The RFC5321.MailFrom or RFC5322.From domain that this pause affects. |
| Recipient Domain |
The recipient domain that this pause affects. |
| Pause Type |
The type of pause – either |
| Throttle ID |
The internal ID for the throttle on which the pause was triggered. |
| Throttle Domains |
The (first 3) domains in the throttle on which the pause was triggered. |
| Affect % |
The percentage of delivery attempts that match this paused domain that will be deferred.
If this is less than |
This command accepts a --json argument to get its output in JSON format instead of an ASCII table.
Remove Paused Domain
The command greenarrow remove paused_domain will remove the given domain
from the list of domains that are currently paused.
This command accepts the following arguments to filter what pauses are removed:
|
--pause-type
string |
Only remove pauses of this type. May be: |
|
--all
bool |
Remove all pause records (optionally filtered by May not be combined with any of the options below. |
|
--throttle-id
integer |
Only remove pauses that were triggered on the specified throttle id. |
|
--throttle-key
string |
Only remove pauses that were triggered on the specified throttle key. |
|
--recipient-domain
string |
Only remove pauses to this recipient domain. |
|
--message-domain
string |
Only remove pauses from this message domain (either an RFC5321.MailFrom or RFC5322.From domain). |
|
--throttle-domain
string |
Only remove pauses that were detected on a throttle that includes the specified domain. |
Service Management
GreenArrow is composed of many individual processes or services. These commands allows you to start, stop, or restart them individually.
Start one or more GreenArrow sub-services:
greenarrow: Usage:
greenarrow service start [SERVICES...]
This command is used to start one or more GreenArrow sub-services.
Specify one or more of the following:
- senders (sender processes only)
- senders_and_first_attempt_queues (stopping or restarting writes first attempt queues to disk)
- simplemh (includes both hvmail-simplemh and hvmail-simplemh2)
- any other services listed in 'greenarrow service status'
Help Options:
-h, --help Show this help message
Stop one or more GreenArrow sub-services:
greenarrow: Usage:
greenarrow service stop [SERVICES...]
This command is used to stop one or more GreenArrow sub-services.
Specify one or more of the following:
- senders (sender processes only)
- senders_and_first_attempt_queues (stopping or restarting writes first attempt queues to disk)
- simplemh (includes both hvmail-simplemh and hvmail-simplemh2)
- any other services listed in 'greenarrow service status'
Help Options:
-h, --help Show this help message
Restart one or more GreenArrow sub-services:
greenarrow: Usage:
greenarrow service restart [SERVICES...]
This command is used to restart one or more GreenArrow sub-services.
Specify one or more of the following:
- senders (sender processes only)
- senders_and_first_attempt_queues (stopping or restarting writes first attempt queues to disk)
- simplemh (includes both hvmail-simplemh and hvmail-simplemh2)
- any other services listed in 'greenarrow service status'
Help Options:
-h, --help Show this help message
Start or stop one or more GreenArrow sub-services:
greenarrow: Usage:
greenarrow service set_state [up|down] [SERVICES...]
This command is used to set the state (up or down) of one or more GreenArrow sub-services.
Run the command 'greenarrow service status' to see a list of services that can be managed.
Application Options:
--seconds-to-wait= time to wait for the service to be in the correct state
(default: 10)
--seconds-in-state= wait for the service to be in the correct state for this many
seconds (default: 1)
Help Options:
-h, --help Show this help message