Difference between revisions of "Regigate appliance tech"

From regify WIKI
Jump to navigation Jump to search
(28 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
== Report a regigate issue ==
 +
If you think you encountered a bug or some issue with regigate, please note that the regify support needs detailed information about what happened. If you consider to report such to regify support, please make sure that the following information is contained:
 +
 +
# A '''detailed description''' about the issue. For example, what happened and what did you expect?
 +
# If the issue is related to '''routing or rules''', we need the used rule set.
 +
# For '''encryption or decryption issues''', or '''conversation issues''', we mostly need the original messages in MIME format.
 +
#* We need the message in a form that reproduces the issue.
 +
#* Meaning that we need the message in a form as it arrives at regigate (before conversion or encryption/decryption).
 +
#* For this, send us such a message without using regigate to support(at)regify.com in a second step after you sent information of step 1.
 +
# If '''encryption or decryption does not even happen''', we need a debug log from the affected regigate. This will tell us why the message has passed.
 +
#* See below information about debugging on this page.
 +
#* Make sure that the issue happens while debugging is activated.
 +
# Please add '''any additional information that might affect the issue''':
 +
#* Do you use Outlook/Thunderbird/Lotus Notes or other? How about Exchange server?
 +
#* Are there other Gateways in the flow that might affect the issue?
 +
 +
Please always use support(at)regify.com for communication. If you are not a direct regify customer, please send all this information to your regify re-seller. They will verify and forward to regify if first level support is not able to fix your issues.
 +
 
== Debugging regigate ==
 
== Debugging regigate ==
  
Line 16: Line 34:
  
 
=== Set regigate debug level in normal mode ===
 
=== Set regigate debug level in normal mode ===
 +
 +
Please note that below examples affect route 1 (route-1, rfmilter-1 etc). Please adapt this number for debugging other routes.
  
 
  $ vim /etc/rfmilter/route-1/conf.json
 
  $ vim /etc/rfmilter/route-1/conf.json
Line 48: Line 68:
  
 
The return of a valid JSON encoded string (even if it says invalid) points you to a working regigate connection.
 
The return of a valid JSON encoded string (even if it says invalid) points you to a working regigate connection.
 +
 +
== Create SRS handling rules ==
 +
regigate does not support SRS address schema if you plan to encrypt outgoing emails. The reason is, that the SRS address encoding schema does not create a reliable sender account. It just generates a sender using original sender name and current domain. Thus, it is not reliable to find a matching user in the connected regify provider.
 +
 +
One way around the problem of stuck outgoing messages with SRS address schema in regigate is the following:
 +
 +
# Login to your regigate with root account.
 +
# Open regigate appliance menu (run ''regigateConfig'').
 +
# Identify the route for outgoing emails (check your regigate routes menu). Note the number in front of the route name!
 +
# Leave regigate appliance menu.
 +
# Create a file ''/etc/postfix/sender_canonical''
 +
# Insert a RegEx to replace your SRS sender addresses with a generic email address (eg group@company.com). Example: <pre>/^(.*\+srs=)(.*=(sender_1\.lu|sender_2\.lu|sender_3\.lu).*@company\.lu$/ group@company.lu</pre>'''Hint:''' Note that the domain dots in RegEx have to be escaped!<br>See [https://www.postfix.org/regexp_table.5.html postfix regexp_table documentation] for more details on this.<br>&nbsp;
 +
# Edit ''/etc/postfix-milter-<no>/main.cf'' (replace ''<no>'' with the number gathered in step 3 above).
 +
# Add the following line: <pre>sender_canonical_maps = regexp:/etc/postfix/sender_canonical</pre>
 +
# Now restart postfix with the following two calls: <pre>postmap /etc/postfix/sender_canonical</pre><pre>systemctl restart postfix</pre>
 +
# Make sure your regify provider has a regify account on group@company.lu (see step 6).
 +
# Make a note about your settings (especially your RegEx). There is a chance that you have to repeat this after a major regigate upgrade.
 +
 +
 +
'''Explanation:''' This postfix rule is executed before the milter is processing the regigate rules. The RegEx is looking for a SRS encoded sender that matches the domain ''sender_1.li'', ''sender_2.lu'' or ''sender_3.lu'' and replaces this sender with the address ''group@company.lu''. By this, regigate can use a regify account with ''group@company.lu'' to encrypt the message.
  
 
== Updating Rule-Lists automatically ==
 
== Updating Rule-Lists automatically ==
Line 67: Line 107:
  
 
'''Hint:''' If an e-mail is sent to regigate in exactly the moment where the rfmilter is not available because of the restart, the sending MTA will get a 4.x.x error (temporary problem). Normally, an MTA then will try it again in a minute and the e-mail(s) will only be a little late.
 
'''Hint:''' If an e-mail is sent to regigate in exactly the moment where the rfmilter is not available because of the restart, the sending MTA will get a 4.x.x error (temporary problem). Normally, an MTA then will try it again in a minute and the e-mail(s) will only be a little late.
 
== Generic questions ==
 
 
=== I can't paste the signed certificate / the rules / user lists? ===
 
Please note the following hints in order to paste:
 
* If you paste the cert/rules/list and ctrl+d does not work, try pressing the enter key first and then ctrl.d.
 
* Be sure to copy directly from PuTTY to the browser window and back.
 
* Every intermediate software is not allowed to add other line-breaks. If you need to use an external editor in between, please make sure he is not adding or changing the line-breaks.
 
 
=== How to see the current mail-queues ===
 
Simply type
 
 
regimailq
 
 
This script will show you all messages currently stuck in the queues. The number suffixes match the route ids shown in the appliance menu.
 
 
(Available as of regigate appliance V4.1.1 or newer)
 

Revision as of 12:39, 26 January 2023

Report a regigate issue

If you think you encountered a bug or some issue with regigate, please note that the regify support needs detailed information about what happened. If you consider to report such to regify support, please make sure that the following information is contained:

  1. A detailed description about the issue. For example, what happened and what did you expect?
  2. If the issue is related to routing or rules, we need the used rule set.
  3. For encryption or decryption issues, or conversation issues, we mostly need the original messages in MIME format.
    • We need the message in a form that reproduces the issue.
    • Meaning that we need the message in a form as it arrives at regigate (before conversion or encryption/decryption).
    • For this, send us such a message without using regigate to support(at)regify.com in a second step after you sent information of step 1.
  4. If encryption or decryption does not even happen, we need a debug log from the affected regigate. This will tell us why the message has passed.
    • See below information about debugging on this page.
    • Make sure that the issue happens while debugging is activated.
  5. Please add any additional information that might affect the issue:
    • Do you use Outlook/Thunderbird/Lotus Notes or other? How about Exchange server?
    • Are there other Gateways in the flow that might affect the issue?

Please always use support(at)regify.com for communication. If you are not a direct regify customer, please send all this information to your regify re-seller. They will verify and forward to regify if first level support is not able to fix your issues.

Debugging regigate

Set regigate debug level in HA mode

$ vim /d1/etc/rfmilter/route-1/conf.json

Change "logLevel" to be "verb" instead of "info" and save. Now restart rfmilter using

$ svc -t /service/rfmilter1-1/

You can inspect the log now using:

$ tail -f /d1/log/rfmilter/debug-1.log

Please, don't forget to reset log level to "info" after you fixed your issues.

Set regigate debug level in normal mode

Please note that below examples affect route 1 (route-1, rfmilter-1 etc). Please adapt this number for debugging other routes.

$ vim /etc/rfmilter/route-1/conf.json

Change "logLevel" to be "verb" instead of "info" and save. Now restart rfmilter using

$ svc -t /service/rfmilter-1/

You can inspect the log now using:

$ tail -f /var/log/rfmilter/debug-1.log

Please, don't forget to reset log level to "info" after you fixed your issues.

Test valid provider connection

There are several tests available for you to be executed on regigate:

 $ curl -k https://regify.company.com:9001/
 curl: (7) Failed connect to regify.company.com:9001; No route to host

The above result means, firewall not setup correctly or wrong regigate IP entered at provider, which equals firewall not set up.

 $ curl -k https://regify.company.com:9001/
 curl: (35) error:14094410:SSL routines:SSL3_READ_BYTES:sslv3 alert 

Above you can see an SSL handshake error because of certificate issue. Maybe the cert from regigate needs to get signed again by the regify provider.

As a final test for full functionality, you can do this (for HA mode, you have to replace /etc with /d1/etc):

$ curl -k --key /etc/rfmilter/route-1/client.key -E /etc/rfmilter/route-1/client.crt https://regify.company.com:9001/
{"status":"INVALID","code":2,"desc":"","version":"4.0.10.5814"}

The return of a valid JSON encoded string (even if it says invalid) points you to a working regigate connection.

Create SRS handling rules

regigate does not support SRS address schema if you plan to encrypt outgoing emails. The reason is, that the SRS address encoding schema does not create a reliable sender account. It just generates a sender using original sender name and current domain. Thus, it is not reliable to find a matching user in the connected regify provider.

One way around the problem of stuck outgoing messages with SRS address schema in regigate is the following:

  1. Login to your regigate with root account.
  2. Open regigate appliance menu (run regigateConfig).
  3. Identify the route for outgoing emails (check your regigate routes menu). Note the number in front of the route name!
  4. Leave regigate appliance menu.
  5. Create a file /etc/postfix/sender_canonical
  6. Insert a RegEx to replace your SRS sender addresses with a generic email address (eg group@company.com). Example:
    /^(.*\+srs=)(.*=(sender_1\.lu|sender_2\.lu|sender_3\.lu).*@company\.lu$/ group@company.lu
    Hint: Note that the domain dots in RegEx have to be escaped!
    See postfix regexp_table documentation for more details on this.
     
  7. Edit /etc/postfix-milter-<no>/main.cf (replace <no> with the number gathered in step 3 above).
  8. Add the following line:
    sender_canonical_maps = regexp:/etc/postfix/sender_canonical
  9. Now restart postfix with the following two calls:
    postmap /etc/postfix/sender_canonical
    systemctl restart postfix
  10. Make sure your regify provider has a regify account on group@company.lu (see step 6).
  11. Make a note about your settings (especially your RegEx). There is a chance that you have to repeat this after a major regigate upgrade.


Explanation: This postfix rule is executed before the milter is processing the regigate rules. The RegEx is looking for a SRS encoded sender that matches the domain sender_1.li, sender_2.lu or sender_3.lu and replaces this sender with the address group@company.lu. By this, regigate can use a regify account with group@company.lu to encrypt the message.

Updating Rule-Lists automatically

If you created rules that are using lists (eg user-list or domain-list), you may feel the need to write such lists (eg by some LDAP synchronization) and update the regigate lists automatically. It is important that the initial list is generated using the appliance menu (even if empty). Upon this you can update the lists automatically if needed.

The lists are located in the filesystem:

/service/rfmilter-n/rules/ 

or, if using HA mode:

/service/rfmilter[12]-n/rules/

A list is ending with the extension .txt. Please do not touch the automatically generated .cdb files. If you updated such a list file in these folders, the list needs to be compiled (compilation is for better speed and creates the .cdb file).
This is done by restarting the rfmilter service as root:

svc -t /service/rfmilter-n

or, if using HA mode:

svc -t /service/rfmilter[12]-n

If you updated several lists, you may want to restart all rfmilter instances at once by calling:

svc -t /service/rfmilter*

Hint: If an e-mail is sent to regigate in exactly the moment where the rfmilter is not available because of the restart, the sending MTA will get a 4.x.x error (temporary problem). Normally, an MTA then will try it again in a minute and the e-mail(s) will only be a little late.