This plugin is no longer maintained. Official support for this implementation ended on 5/31/2018.
Version 1.3.2
The Black Duck Hub Email Extension runs independently from the Hub and provides additional functionality. It automatically sends email alerts and information that you need to know, based on your preferences.
Triggering events in the Hub generate an email alert. You can specify the triggering events, based on your personal preferences and workflow needs. Emails can be sent:
As a Hub user, the Hub Email Extension enables you to:
After installing and configuring the Hub Email Extension, email digests are automatically sent to all users opted-in for email notifications. No further user interaction is required. You can change the global configuration as needed, and you can edit your personal preferences at any time.
The Hub Email Extension installer is available as a .zip file at GitHub. Download the .zip file, and then install as follows.
To download the Hub Email Extension installer:
hub-email-extension-version_number.zip
The following installation routine is for a Dockerized environment. To install in a non-Dockerized environment, refer to Installing the Hub Email Extension in a non-Dockerized Environment.
To install the Hub Email Extension in a Dockerized environment (Black Duck Hub versions 3.7, 4.1.0, and higher), use the following procedure.
Hub Email Extension is not compatible with Black Duck Hub version 4.0.0. |
The Hub cannot be running during the installation of the Hub Email Extension. Stop the Hub using the command:
|
Update the docker-compose.yml
file to include the email extension. Add the following section to the docker-compose.yml
file after the webserver:
section and before the volumes:
section.
Be sure to change the <version> tag to the appropriate version of the email extension image. For example, 1.2.0
or 1.2.0-SNAPSHOT
|
At the end of the docker-compose.yml
file, you must modify the existing volume list and add the newly created email-extension-config-volume. Add the following lines to your docker-compose.yml
file.
volumes: {data-volume: null, cert-volume: null, config-volume: null, log-volume: null, webserver-volume: null, webapp-volume: null, search-volume: null, email-extension-config-volume: null} |
If using a proxy, include the following:
hub-email-extension: links: [webapp, cfssl] image: blackducksoftware/hub-email-extension:<version> container_name: hub-email-extension ports: ['55000:55000'] volumes: ['email-extension-config-volume:/opt/blackduck/extensions'] env_file: [hub-webserver.env, hub-proxy.env] |
Running the Hub Email Extension in an environment wherein your Hub instance is behind a proxy, and your email server is also behind a proxy is not currently supported. This functionality will be added in a future version of the Hub Email Extension. |
The certificate is imported automatically by the docker-entrypoint.sh file. If the import fails, the Docker log <email_extension_container_id> displays log messages for importing the certificate. If an error occurred, then the error messages display in the log at the startup of the container.
If the auto import fails, you can perform a manual import of the certificate as follows.
Stop the Hub using the following command.
docker-compose -file docker-compose.yml -p hub down |
hub_email_extension: links: [webapp, cfssl] image: blackducksoftware/hub-email-extension:1.2.2-SNAPSHOT container_name: hub-email-extension ports: ['55000:55000'] volumes: ['email-extension-config-volume:/opt/blackduck/extensions'] env_file: [hub-webserver.env] environment: {EMAIL_EXT_IMPORT_CERT=false} |
After configuring the docker-compose.yml file to include the email extension, you must start the Hub. To start the Hub, execute the following command:
|
When you start the Hub, you may see log messages for the Hub containers in the command line window.
Use the following command to copy the certificate. Replace <certificate file> with your certificate path, and replace <container_id> with the email extensions ID. <dest_path> is your selected location in the container.
docker cp <certificate_file> <container_id>:<dest_path> |
Use the following command to execute the shell into the container. Replace <container_id> with the email extensions ID.
docker exec -it <container_id> /bin/sh |
Execute the following command to import the Hub certificate into the cacerts file of the email extension container. Double-click to select the entire code example for copying and pasting. Make sure you fit the entire command on a single line prior to executing. Note that the <file_copied> property is the file named in the certificate copy step. For <publichubwebserver>, you can use the default name, or supply your own. Supplying your own can be helpful in case auto-import is accidentally enabled.
If the line environment: {EMAIL_EXT_IMPORT_CERT=false} is omitted, or if the value is true, auto-import is enabled. |
keytool -importcert -file <file_copied> -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit -alias <publichubwebserver or custom name> -noprompt' -v |
If you change the certificate on the Hub server, you must update the publichubwebserver. This is accomplished using keytool -delete to remove the certificate with the publichubwebserver alias from the email extension container. |
When running Hub Email Extension, you must import the proper certificate into your Java. Oherwise, a PKIX error is generated. You can implicitly trust all certificates using the following configuration.
This is a convenience feature, and your certificates should be imported by your administrator. Black Duck recommends that you configure certificates based on your specific environment. |
Use the following steps:
Use the following command to stop the Hub.
docker-compose -file docker-compose.yml -p hub down |
Use the following to edit the compose file.
hub_email_extension: links: [webapp, cfssl] image: blackducksoftware/hub-email-extension:1.2.2-SNAPSHOT container_name: hub-email-extension ports: ['55000:55000'] volumes: ['email-extension-config-volume:/opt/blackduck/extensions'] env_file: [hub-webserver.env, hub-proxy.env] environment: { EMAIL_EXT_IMPORT_CERT=false, EXTENSION_ALWAYS_TRUST_SERVER_CERTIFICATE=true } |
This is a convenience feature, and your certificates should be imported by your administrator. Black Duck recommends that you configure certificates based on your specific environment. |
Use the following command to start the Hub.
docker-compose -file docker-compose.yml -p hub up -d |
If the email extension is to be run with an SSL certificate, the procedure to update the certificates is the same. Follow the Configuring for SSL section in this documentation. However, you must use a command line on the container to execute the required commands. Use docker exec
to open a command line in the email extension container. Then, execute the following steps.
Configure the Hub Email Extension in your Dockerized environment as follows.
http://hub-email-extension:55000
If you can add the Hub Email Extension, but cannot authorize it, then the Docker network may have failed after the IP table service is restarted, which is described here: https://github.com/moby/moby/issues/12294. This usually manifests as an unknown host exception in the hub-webapp container when trying to communicate with the email extension container, and is related to the IP table rules on the Docker bridge network. To address the issue, incoming traffic from the Docker bridge must be allowed where the destination port is 443/tcp and 55000/tcp.
There are two approaches to address the issue. Choose the approach that best fits your IT security policies.
Allow traffic to those ports coming from any network interface:
iptables -I INPUT 1 -p tcp --dport 443 -j ACCEPT iptables -I INPUT 1 -p tcp --dport 55000 -j ACCEPT |
Allow traffic coming from the Docker bridge:
iptables -I INPUT 1 -i <docker_bridge_NIC> -j ACCEPT |
Use the following code to create email extension-named volumes.
hub-email-extension: image: blackducksoftware/hub-email-extension:<version> depends_on: [webapp] container_name: hub-email-extension ports: ['55000:55000'] volumes: ['email-extension-config-volume:/opt/blackduck/extensions'] env_file: hub-webserver.env |
To upgrade your existing version of the Hub Email Extension, use the following procedure.
The following topics are configuration procedures that must be performed for both Hub server and non-Hub system environments.
You must configure the extension. The first step is to select an available port. By default, the extension contains port 8000 in its URL. However, based on your environment, this port may not be available.
Check port numbers
For more information on TCP and UDP port numbers, refer to https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers.
To check the port number:
To avoid collisions with known ports, port number 55000 will be used.
Next, change the URL for the email extension to match the server name used to access the Hub. Change the port to 55000.
To edit the file:
Execute the command:
vi /opt/blackduck/extensions/hub-email-extension-<version>/config/extension.properties |
Find the hub.extension.url property:
hub.extension.url=http\//:localhost\:8000 |
Edit the URL so that the host name matches the host name used to access the Hub, and change the port number to 55000:
hub.extension.url=http://hub.server.url:55000 |
Save the changes to extension.properties.
To configure the email extension to run over Secure Socket Layers (SSL), then the extension.properties file must be configured to be aware of the certificate in use. If the Hub server is running over SSL, then the certificate for Hub communication over SSL can be used here as well.
Prerequisites:
To configure for SSL:
Execute the command:
vi /opt/blackduck/extensions/hub-email-extension-<version>/config/extension.properties. |
Locate the following section for SSL configuration:
# HTTPS optional config hub.extension.ssl.keyStorePath= hub.extension.ssl.keyStorePassword= hub.extension.ssl.keyPassword= hub.extension.ssl.keyStoreType= |
Edit the path to the certificate file:
# HTTPS optional config hub.extension.ssl.keyStorePath=/opt/blackduck/install/certificate.pkcs12 hub.extension.ssl.keyStorePassword= hub.extension.ssl.keyPassword= hub.extension.ssl.keyStoreType= |
Edit the keystore password:
# HTTPS optional config hub.extension.ssl.keyStorePath=/opt/blackduck/install/certificate.pkcs12 hub.extension.ssl.keyStorePassword=keystorepassword hub.extension.ssl.keyPassword= hub.extension.ssl.keyStoreType= |
Edit the key password. Note that for PKCS12 keystores, the keystore password and the key password are the same.
# HTTPS optional config hub.extension.ssl.keyStorePath=/opt/blackduck/install/certificate.pkcs12 hub.extension.ssl.keyStorePassword=keystorepassword hub.extension.ssl.keyPassword=keystorepassword hub.extension.ssl.keyStoreType= |
Edit the keystore type:
# HTTPS optional config hub.extension.ssl.keyStorePath=/opt/blackduck/install/certificate.pkcs12 hub.extension.ssl.keyStorePassword=keystorepassword hub.extension.ssl.keyPassword=keystorepassword hub.extension.ssl.keyStoreType=PKCS12 |
After this is configured, you can start the Hub Email Extension.
At this point, the Hub Email Extension should be configured such that it can be started. Run the email_extension.sh script file as the original user.
Use the following commands for testing your configuration.
Starting the extension:
/opt/blackduck/extensions/hub-email-extension-<version>/bin/email_extension.sh start |
Stopping the extension:
/opt/blackduck/extensions/hub-email-extension-<version>/bin/email_extension.sh stop |
Checking the status:
/opt/blackduck/extensions/hub-email-extension-<version>/bin/email_extension.sh status |
If the start command doesn't report a pid number, then the Hub Email Extension configuration may be wrong; specifically permissions on folders. Refer to the logs for more details.
Check the log file at: /opt/blackduck/extensions/hub-email-extension-<version>/logs
.
The first time the extension starts, the log contains the following message:
09:28:27.362 [main] ERROR com.blackducksoftware.integration.email.EmailEngine - Error Starting Email Engine java.lang.IllegalStateException: No token present to refresh at com.blackducksoftware.integration.email.extension.server.oauth.TokenManager.refreshUserAccessToken(TokenManager.java:204) ~[hub-email-extension-1.1.0.jar:?] at com.blackducksoftware.integration.email.extension.server.oauth.TokenManager.refreshToken(TokenManager.java:140) ~[hub-email-extension-1.1.0.jar:?] at com.blackducksoftware.integration.email.EmailEngine.start(EmailEngine.java:187) [hub-email-extension-1.1.0.jar:?] at com.blackducksoftware.integration.email.Application.<init>(Application.java:61) [hub-email-extension-1.1.0.jar:?] at com.blackducksoftware.integration.email.Application.main(Application.java:38) [hub-email-extension-1.1.0.jar:?] |
This is not a failure of the extension to start. It indicates that the extension has not been authorized.
Once the extension is up and running, you can get the extension information through the URL:
http(s)://hub.server.url:55000/extension/info
If the URL for which the extension is configured doesn't work, make sure port 55000 is open for accepting connections. To do so, you must create iptable rules to open the ports. You may need to configure two rules to open the port for the email extension.
Due to differences in Linux distributions, Black Duck recommends that you consult your IT department before performing the following steps. |
To get the extension information from the URL:
Stop the email extension using the command:
/opt/blackduck/extensions/hub-email-extension-<version>/bin/email_extension.sh stop |
Execute the command:
iptables -I INPUT -m tcp -p tcp --dport 55000 -j ACCEPT |
Then, execute the command:
iptables -I OUTPUT -m tcp -p tcp --dport 55000 -j ACCEPT |
Start the email extension using the command:
/opt/blackduck/extensions/hub-email-extension-<version>/bin/email_extension.sh start |
After the URL displays the JSON payload describing the extension, you can register the extension as normal.
After you have successfully installed the Hub Email Extension, you must authenticate and configure the extension. The steps are:
These procedures are described in the following sections.
Additional configuration options including:
are also described in the following sections.
After installing the Hub Email Extension, you must complete the extension authentication process.
You must have administrator rights to perform authentications. |
To authenticate the Hub Email Extension:
After you have successfully installed and authenticated the Hub Email Extension, you must configure it for your environment. This is referred to as the global configuration. You must have administrator rights to configure the email extension.
If the Hub Email Extension is not running, then the Hub Email Extension > Extension Configuration section does not display. |
To globally configure and authenticate the Hub Email Extension:
By default, all users are opted-in for the email digest. Administrator users can edit the user.configuration.json
file to globally opt all users in or out. Users can configure their personal settings to opt-in or opt-out on an individual basis. For more information, refer to Hub Email Extension user configuration.
After you have successfully installed and authenticated the Hub Email Extension, and configured it for your environment, you can configure it according to your personal preferences. This is referred to as the user configuration. You can change your personal notification email preferences at any time.
To configure your user preferences for the Hub Email Extension:
As a Hub administrator, you can determine a custom interval for delivery of your notification email digests. Distribution options are:
Setting up a custom email notification option may be a better fit for your workflow, and can allow greater flexibility for your users.
To configure a custom notification email distribution schedule:
Open the Properties file, and locate the lines:
# default custom interval is to run every hour hub.email.notifier.variable.customDigest.cron.expression=0 0 0/1 1/1 * ? * |
The default custom setting sends notification emails in an hourly digest. You can keep this setting, or configure your custom distribution to fit your workflow requirements. |
Because Hub extensions require Cron job settings using Cron expressions and syntax, reference websites and examples are provided in Cron Reference Information for Hub Extensions. |
The Hub Email Extension supports JavaMail configuration properties. This is achieved by adding properties to the extension.properties file beginning with the prefix hub.email.javamail.config
. This allows an administrator of the extension to configure the full set of JavaMail properties as outlined on the Oracle website:
https://docs.oracle.com/javaee/7/api/javax/mail/package-summary.html
If you are using an authenticated SMTP server, specify the following properties in your extension.properties file to configure the user name and password.
hub.email.javamail.config.mail.smtp.user=<username> hub.email.javamail.config.mail.smtp.password=<password> hub.email.javamail.config.mail.smtp.auth=true |
If your environment includes an SMTP server requiring SSL, use the parameter:
hub.email.javamail.config.mail.smtp.ssl.enable=true |
If your environment includes an SMTP server using TLS, use the parameter:
hub.email.javamail.config.mail.smtp.starttls.enable=true |
With SSL or TLS enabled, the certificates must be in a trust store recognized by the JVM to use SSL or TLS. |
For additional JavaMail SMTP configuration properties, refer to https://javaee.github.io/javamail/docs/api/com/sun/mail/smtp/package-summary.html.
The Hub Email Extension supports SSL communication between the Hub and the extension. The certificate used by the extension must be signed by a certificate authority (CA) that the Hub server recognizes in its keystore for the Hub server to create a Secure Socket Layers (SSL) handshake between the Hub and the extension.
In the extension.properties file, the property hub.extension.url must contain https as the protocol scheme in the URL. For example, https://localhost:8000.
Next, the optional SSL parameters in the extension.properties file must contain valid values as follows:
For more information, refer to the Restlet documentation located at:
https://restlet.com/technical-resources/restlet-framework/guide/2.3/core/security/https
The Hub Email Extension features a test page that is hosted by the extension. After authorizing and configuring the extension, you can use the test page to verify that your configuration is correct. The test page is accessed using the URL http://<extension_host_and_port>/extension/test. For example, http://mailextension.company.com:8000/extension/test.
To test your Hub Email Extension configuration:
When restarting the Hub Email Extension container, you must delete the extension from the Hub, re-add it, and then authorize the extension. When adding the extension to the Hub, note that if the container is restarted, you must delete the extension and perform these steps again.
If the Hub Email Extension is no longer required, you can uninstall it using the following process.
To uninstall the Hub Email Extension:
After removing the Hub Email Extension, the installation and configuration files remain on your system. Therefore, you can reinstall the Hub Email Extension at any time. For more information, refer to the Hub Email Extension installation section. |
Cron is a Unix tool with an established history. Its scheduling capabilities are both powerful and proven. The CronTrigger class is based on the scheduling capabilities of Cron.
CronTrigger uses Cron expressions, which are able to create distribution schedules such as:
For information and resources on cron syntax and more, refer to Cron Job References.
Should you experience difficulties with your Hub Email Extension, refer to the following topics for troubleshooting techniques.
If you cannot retrieve the extension information, try running the following commands.
List the iptables:
iptables -L INPUT |
Check if the port is listed:
iptables -L OUTPUT |
netstat -nap | grep -i '<port_number>' |
If nothing is returned, then the Hub Email Extension either isn't able to use the port, or the Hub Email Extension isn't running.
Scenario: you register the Hub Email Extension, and then delete it from the Hub. Before you can register and authorize it again, you must complete the following procedure.
To re-register and re-authorize the Hub Email Extension:
Stop the extension using the command:
/opt/blackduck/extensions/hub-email-extension-<version>/bin/email_extension.sh stop |
Delete the file containing the token using the command:
/opt/blackduck/extensions/hub-email-extension-<version>/config/oauth.properties |
Start the extension using the command:
/opt/blackduck/extensions/hub-email-extension-<version>/bin/email_extension.sh start |
To properly set the firewall with CentOS versions 7.0 and higher, use the firewall-cmd command. If you have questions, refer to the manual page of the firewall-cmd command. Additionally, consult your IT department if you have further questions regarding requirements within your specific environment.
The following sections address specific areas of CentOS firewall configurations. Run the commands in the sections pertaining to your firewall configuration issues.
Check if firewalld is running:
To verify that the firewalld firewall service is running, use the following commands:
>systemctl status firewalld firewalld.service - firewalld - dynamic firewall daemon Loaded: loaded (/usr/lib/systemd/system/firewalld.service; disabled; vendor preset: enabled) Active: inactive (dead) |
Open ports
If firewalld is running, use the following command to open the appropriate ports:
>firewall-cmd --zone=public --add-port=<port number>/tcp --permanent |
Consult with your IT department before opening ports. |
You must open the following port:
Example:
>firewall-cmd --zone=public --add-port=55000/tcp --permanent |
For the firewall changes to take effect, you must issue the reload command:
>firewall-cmd --reload |