Postkutsche

A module that combines PowerDns and Mailcow to create a mail domain with all required entries on both services in a single command.

Install

yarn add postkutsche

or

npm i postkutsche

Basic use

(async () => {
    //import the process.env variables from the .env file in which you should store them
    //you can install dotenv with `npm i dotenv --save-dev` or `yarn add dotenv --dev`
    require('dotenv').config();

    //import the Postkutsche class
    const {
        Postkutsche
    } = require("./index.js");

    //create a new instance of Postkutsche providing it with the necessary api keys
    const pk = new Postkutsche({
        mailcow: {
            url: process.env.MAILCOW_API_URL,
            apikey: process.env.MAILCOW_API_KEY
        },
        powerdns: {
            url: process.env.PDNS_API_URL,
            apikey: process.env.PDNS_API_KEY
        }
    });

    const info={
        nameserver: ['ns1.domain.tld', 'ns2.domain.tld', 'ns3.domain.tld'],
        hostmasterEmail: '[email protected]',
        dmarcMail: '[email protected]', 
        mailDomain: 'domain.tld',
        mailServerHostname: 'mail.domain.tld',
        defaultMailbox: {
            local_part: `max.mustermensch`,
            name: `Max Mustermensch`
        },
        //NEEDED FOR MAILSERVER DOMAIN SETUP
        mailServerIp: '2a00:1450:4016:801::2003', //Your IPv6 address WITHOUT brackets([]) 
        mailServerLegacyIp: '127.0.0.1',//Your IPv4 address
        addLetsEncryptCAA: true,
        caaReportMail: '[email protected]' //can be set if you want to get reports on malicious cert issues
    }

    //use a function from the Postkutsche class
    //adds the mail records for a domain and creates the domain on mailcow
    await pk.addMailDomain(info);
})();

Need help or missing a feature?

Feel free to contact me via [email protected] in english or german

Links

NPM

Documentation

Code

powerdns-api

NPM

Documentation

Code

mailcow-api

NPM

Documentation

Code

Modules

Typedefs

postkutsche

• postkutsche
  • .Postkutsche
    • new module.exports.Postkutsche(info)
    • .getTLSA(info) ⇒ Array
    • .genMailDomainRecords(info) ⇒ Array
    • .addMailDomain(info, [log]) ⇒ Boolean
    • .addMailServerDnsRecords(info, [log]) ⇒ Boolean
    • .openpgpHash(localPart)
    • .openpgpRecord(localPart, publicKeyB64) ⇒ OpenpgpRecord
    • .setOpenpgpRecord(localPart, domain, publicKeyB64)
    • .cleanupAddMailServer(info)
    • .cleanupAddMailDomain(info)

postkutsche.Postkutsche

Class representing the Postkutsche client

Kind: static class of postkutsche

• .Postkutsche
  • new module.exports.Postkutsche(info)
  • .getTLSA(info) ⇒ Array
  • .genMailDomainRecords(info) ⇒ Array
  • .addMailDomain(info, [log]) ⇒ Boolean
  • .addMailServerDnsRecords(info, [log]) ⇒ Boolean
  • .openpgpHash(localPart)
  • .openpgpRecord(localPart, publicKeyB64) ⇒ OpenpgpRecord
  • .setOpenpgpRecord(localPart, domain, publicKeyB64)
  • .cleanupAddMailServer(info)
  • .cleanupAddMailDomain(info)

new module.exports.Postkutsche(info)

Create a postkutsche client.

| Param | Type | Description | | --- | --- | --- | | info | ApiInfo | The provided ApiInfo object |

Example

(async () => {
    //import the process.env variables from the .env file in which you should store them
    //you can install dotenv with `npm i dotenv --save-dev` or `yarn add dotenv --dev`
    require('dotenv').config();

    //import the Postkutsche class
    const {
        Postkutsche
    } = require("./index.js");

    //create a new instance of Postkutsche providing it with the necessary api keys
    const pk = new Postkutsche({
        mailcow: {
            url: process.env.MAILCOW_API_URL,
            apikey: process.env.MAILCOW_API_KEY
        },
        powerdns: {
            url: process.env.PDNS_API_URL,
            apikey: process.env.PDNS_API_KEY
        }
    });

    const info={
        nameserver: ['ns1.domain.tld', 'ns2.domain.tld', 'ns3.domain.tld'],
        hostmasterEmail: '[email protected]',
        dmarcMail: '[email protected]', 
        mailDomain: 'domain.tld',
        mailServerHostname: 'mail.domain.tld',
        defaultMailbox: {
            local_part: `max.mustermensch`,
            name: `Max Mustermensch`
        },
        //NEEDED FOR MAILSERVER DOMAIN SETUP
        mailServerIp: '2a00:1450:4016:801::2003', //Your IPv6 address WITHOUT brackets([]) 
        mailServerLegacyIp: '127.0.0.1',//Your IPv4 address
        addLetsEncryptCAA: true,
        caaReportMail: '[email protected]' //can be set if you want to get reports on malicious cert issues
    }

    //use a function from the Postkutsche class
    //adds the mail records for a domain and creates the domain on mailcow
    await pk.addMailDomain(info);
})();

postkutsche.getTLSA(info) ⇒ Array

Kind: instance method of Postkutsche
Returns: Array - with tlsa records ready to be inserted into powerdns

| Param | Type | Description | | --- | --- | --- | | info | Info | Info object with the necessary information to generate the tlsa records |

Example

await pk.getTLSA({
            mailServerHostname: 'mail.domain.tld',
            mailServerIp: '2a00:1450:4016:801::2003',
            mailServerLegacyIp: '127.0.0.1'
        });

postkutsche.genMailDomainRecords(info) ⇒ Array

Kind: instance method of Postkutsche
Returns: Array - with domain relevant mail records

| Param | Type | Description | | --- | --- | --- | | info | Info | Info object with the necessary information to generate the domain mail records |

Example

pk.genMailDomainRecords({
            mailServerHostname: 'mail.domain.tld',
            mailDomain: 'domain.tld',
            dmarcMail: '[email protected]'
        });

postkutsche.addMailDomain(info, [log]) ⇒ Boolean

This will add:

• Mailcow:
  • Domain (if not present)
  • Mailbox (if not present)
  • DKIM Key (if not present)
  • Alias: catchall (catchall will relay everything @yourdomain.tld to your Mailbox) (if not present)
• PowerDns:
  • Domain (if not present)
  • Mail records for the domain (won't touch other records but will overwrite present matching records)
  • DNSSEC (if domain wasn't present)
  • Create record on mailServerDomain(if not the same as mailDomain) to allow dmarc mails to sent to this domain

Kind: instance method of Postkutsche
Returns: Boolean - true on success

| Param | Type | Default | Description | | --- | --- | --- | --- | | info | Info | | Info object with the necessary information to create a mail domain on mailcow and the necessary records on powerdns | | [log] | Boolean | true | you can disable logging by setting this to false |

Example

await pk.addMailDomain({
            nameserver: ['ns1.domain.tld', 'ns2.domain.tld', 'ns3.domain.tld'],
            hostmasterEmail: '[email protected]',
            dmarcMail: '[email protected]', 
            mailDomain: 'domain.tld',
            mailServerHostname: 'mail.domain.tld',
            defaultMailbox: {
                local_part: `max.mustermensch`,
                name: `Max Mustermensch`,
                password:`set some good password here` //can be omitted
            }
        });

postkutsche.addMailServerDnsRecords(info, [log]) ⇒ Boolean

This will add:

• PowerDns:
  • Domain for the mailserver hostname (if not present)
  • DNSSEC (will replace old dnssec if present)
  • TLSA records for the domain (for the creation of the tlsa records you need to have openssl installed. you can specify the path, if it can't be found globally as 'openssl')
  • Records for the mailserver

Kind: instance method of Postkutsche
Returns: Boolean - true on success

| Param | Type | Default | Description | | --- | --- | --- | --- | | info | Info | | Info object with the necessary information to create the relevant records for the mailserver | | [log] | Boolean | true | you can disable logging by setting this to false |

Example

await pk.addMailServerDnsRecords({
            nameserver: ['ns1.domain.tld', 'ns2.domain.tld', 'ns3.domain.tld'],
            hostmasterEmail: '[email protected]',
            mailServerHostname: 'mail.domain.tld',
            mailServerIp: '2a00:1450:4016:801::2003', //Your IPv6 address WITHOUT brackets([]) 
            mailServerLegacyIp: '127.0.0.1',//Your IPv4 address
            addLetsEncryptCAA: true,
            caaReportMail: '[email protected]' //can be set if you want to get reports on malicious cert issues
    });

postkutsche.openpgpHash(localPart)

Creates the front part of the openpgp dns record

Kind: instance method of Postkutsche

| Param | Type | Description | | --- | --- | --- | | localPart | String | local part of your email address (the part before the @ not including the @) |

Example

console.log(pk.openpgpHash('max.mustermensch'));

postkutsche.openpgpRecord(localPart, publicKeyB64) ⇒ OpenpgpRecord

Creates an openpgp dns record

Kind: instance method of Postkutsche

| Param | Type | Description | | --- | --- | --- | | localPart | String | local part of your email address (the part before the @ not including the @) | | publicKeyB64 | String | your publickey in base64 (it should be correct if it includes -----BEGIN PGP PUBLICKEY BLOCK-----) or only contains these characters: A-Z a-z 0-9 + / |

Example

console.log(pk.openpgpRecord('max.mustermensch','-----BEGIN PGP (...)'));

postkutsche.setOpenpgpRecord(localPart, domain, publicKeyB64)

Sets an openpgp record on your powerdns server Will overwrite key with the same local part

Kind: instance method of Postkutsche

| Param | Type | Description | | --- | --- | --- | | localPart | String | local part of your email address (the part before the @ not including the @) | | domain | String | the domain you want to add the key to | | publicKeyB64 | String | your publickey in base64 (it should be correct if it includes -----BEGIN PGP PUBLICKEY BLOCK-----) or only contains these characters: A-Z a-z 0-9 + / |

Example

await pk.setOpenpgpRecord('max.mustermensch','domain.tld','-----BEGIN PGP (...)');

postkutsche.cleanupAddMailServer(info)

Will delete the complete mailserver domain from powerdns

Kind: instance method of Postkutsche

| Param | Type | Description | | --- | --- | --- | | info | Info | Info object with the necessary information to delete the mailserver domain |

Example

pk.cleanupAddMailServer({mailServerHostname:'mail.domain.tld'});

postkutsche.cleanupAddMailDomain(info)

Will delete a domain from powerdns and mailcow THIS WILL DELETE YOUR MAILBOX AND EVERYTHING ELSE CONCERNING THIS DOMAIN

Kind: instance method of Postkutsche

| Param | Type | Description | | --- | --- | --- | | info | Info | Info object with the necessary information to create a mail domain on mailcow and the necessary records on powerdns |

Example

await pk.cleanupAddMailDomain({
             dmarcMail: '[email protected]', 
             mailDomain: 'domain.tld',
             defaultMailbox: {
                 local_part: `max.mustermensch`,
                 name: `Max Mustermensch`
             }
         });

ApiInfo : object

Kind: global typedef
Properties

| Name | Type | | --- | --- | | mailcow | object | | mailcow.url | string | | mailcow.apikey | string | | powerdns | object | | powerdns.url | String | | powerdns.apikey | String |

Example

{
        mailcow: {
            url: process.env.MAILCOW_API_URL,
            apikey: process.env.MAILCOW_API_KEY
        },
        powerdns: {
            url: process.env.PDNS_API_URL,
            apikey: process.env.PDNS_API_KEY
        }
    }

Info : object

Kind: global typedef
Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | nameserver | Array.<string> | | array of nameservers for your domain, first ns in the list will be used as primary | | hostmasterEmail | string | | hostnmaster email address | | [dmarcMail] | string | | add mail if you want to get dmarc reports | | mailDomain | string | | the domain you may want to add mail for | | mailServerHostname | String | | the hostname of the mailserver | | defaultMailbox | Object | | | | defaultMailbox.local_part | String | | local part of you mailbox (the part before the @ not including the @) | | defaultMailbox.name | String | | the name of mailbox | | [defaultMailbox.password] | String | RANDOM | will generate a random password for your mailbox if omitted | | mailServerIp | String | | IPv6 address of your mailserver | | mailServerLegacyIp | String | | IPv4 address of your mailserver | | [addLetsEncryptCAA] | Boolean | | enable this option if you are ONLY using letsencrypt certs | | [caaReportMail] | String | | | | [openssl_path] | String | 'openssl' | optional alternative path for openssl |

Example

{
        nameserver: ['ns1.domain.tld', 'ns2.domain.tld', 'ns3.domain.tld'],
        hostmasterEmail: '[email protected]',
        dmarcMail: '[email protected]', 
        mailDomain: 'domain.tld',
        mailServerHostname: 'mail.domain.tld',
        defaultMailbox: {
            local_part: `max.mustermensch`,
            name: `Max Mustermensch`
        },
        //NEEDED FOR MAILSERVER DOMAIN SETUP
        mailServerIp: '2a00:1450:4016:801::2003', //Your IPv6 address WITHOUT brackets([]) 
        mailServerLegacyIp: '127.0.0.1',//Your IPv4 address
        addLetsEncryptCAA: true,
        caaReportMail: '[email protected]' //can be set if you want to get reports on malicious cert issues
    }