1. Overview
2. Module Description - What does the module do?
3. Setup - The basics of getting started with mongodb
4. Usage - Configuration options and additional functionality
5. Reference - An under-the-hood peek at what the module is doing and how
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module

Installs MongoDB on RHEL/Ubuntu/Debian from OS repo, or alternatively from MongoDB community/enterprise repositories.

The MongoDB module manages mongod server installation and configuration of the mongod daemon. For the time being it supports only a single MongoDB server instance, without sharding functionality.

The MongoDB module also manages Ops Manager setup and the mongdb-mms daemon.

• MongoDB package.
• MongoDB configuration files.
• MongoDB service.
• MongoDB client.
• MongoDB sharding support (mongos)
• MongoDB apt/yum repository.
• Ops Manager package.
• Ops Manager configuration files.

If you just want a server installation with the default options you can run include mongodb::server. If you need to customize configuration options you need to do the following:

class {'mongodb::server':
  port    => 27018,
  verbose => true,
}

For Red Hat family systems, the client can be installed in a similar fashion:

class {'mongodb::client':}

Note that for Debian/Ubuntu family systems the client is installed with the server. Using the client class will by default install the server.

If one plans to configure sharding for a Mongo deployment, the module offer the mongos installation. mongos can be installed the following way :

class {'mongodb::mongos' :
  configdb => ['configsvr1.example.com:27018'],
}

Although most distros come with a prepacked MongoDB server, you may prefer to use a more recent version. To install MongoDB from the community repository:

class {'mongodb::globals':
  manage_package_repo => true,
  version             => '3.6',
}
-> class {'mongodb::client': }
-> class {'mongodb::server': }

If you don't want to use the MongoDB software repository or the OS packages, you can point the module to a custom one. To install MongoDB from a custom repository:

class {'mongodb::globals':
  manage_package_repo => true,
  repo_location => 'https://example.com/repo'
}
-> class {'mongodb::server': }
-> class {'mongodb::client': }

Having a local copy of MongoDB repository (that is managed by your private modules) you can still enjoy the charms of mongodb::params that manage packages. To disable managing of repository, but still enable managing packages:

class {'mongodb::globals':
  manage_package_repo => false,
  manage_package      => true,
}
-> class {'mongodb::server': }
-> class {'mongodb::client': }

Most of the interaction for the server is done via mongodb::server. For more options please have a look at mongodb::server. Also in this version we introduced mongodb::globals, which is meant more for future implementation, where you can configure the main settings for this module in a global way, to be used by other classes and defined resources. On its own it does nothing.

To install MongoDB server, create database "testdb" and user "user1" with password "pass1".

class {'mongodb::server':
  auth => true,
}

mongodb::db { 'testdb':
  user          => 'user1',
  password_hash => 'a15fbfca5e3a758be80ceaf42458bcd8',
}

Parameter 'password_hash' is hex encoded md5 hash of "user1:mongo:pass1". Unsafe plain text password could be used with 'password' parameter instead of 'password_hash'.

To install Ops Manager and have it run with a local MongoDB application server do the following:

class {'mongodb::opsmanager':
  opsmanager_url        => 'https://opsmanager.yourdomain.com'
  mongo_uri             => 'mongodb:https://yourmongocluster:27017,
  from_email_addr       => '[email protected]',
  reply_to_email_addr   => '[email protected]',
  admin_email_addr      => '[email protected]',
  $smtp_server_hostname => 'email-relay.yourdomain.com'
}

The default settings will not set useful email addresses. You can also just run include mongodb::opsmanager and then set the emails later.

Most of the interaction for the server is done via mongodb::opsmanager. For more options please have a look at mongodb::opsmanager.

• mongodb::server: Installs and configure MongoDB
• mongodb::client: Installs the MongoDB client shell (for Red Hat family systems)
• mongodb::globals: Configure main settings in a global way
• mongodb::mongos: Installs and configure Mongos server (for sharding support)
• mongodb::opsmanager: Installs and configure Ops Manager

• mongodb::repo: Manage MongoDB software repository
• mongodb::repo::apt: Manage Debian/Ubuntu apt MongoDB repository
• mongodb::repo::yum: Manage Redhat/CentOS yum MongoDB repository
• mongodb::server::config: Configures MongoDB configuration files
• mongodb::server::install: Install MongoDB software packages
• mongodb::server::service: Manages service
• mongodb::client::install: Installs the MongoDB client software package
• mongodb::mongos::config: Configures Mongos configuration files
• mongodb::mongos::install: Install Mongos software packages
• mongodb::mongos::service: Manages Mongos service

Note: most server specific defaults should be overridden in the mongodb::server class. This class should only be used if you are using a non-standard OS or if you are changing elements such as version or manage_package_repo that can only be changed here.

This class allows you to configure the main settings for this module in a global way, to be used by the other classes and defined resources. On its own it does nothing.

This setting can be used to override the default MongoDB server package name. If not specified, the module will use whatever package name is the default for your OS distro.

This setting can be used to override the default MongoDB service name. If not specified, the module will use whatever service name is the default for your OS distro.

This setting can be used to override the default MongoDB service provider. If not specified, the module will use whatever service provider is the default for your OS distro.

This setting can be used to override the default status check command for your MongoDB service. If not specified, the module will use whatever service name is the default for your OS distro.

This setting can be used to override the default management of the mongod service. By default the module will manage the mongod process.

This setting can be used to override the default management of the mongos service. By default the module will manage the mongos process.

This setting can be used to override the default MongoDB user and owner of the service and related files in the file system. If not specified, the module will use the default for your OS distro.

This setting can be used to override the default MongoDB user group to be used for related files in the file system. If not specified, the module will use the default for your OS distro.

This setting is used to configure MongoDB to turn on ipv6 support. If not specified and ipv6 address is passed to MongoDB bind_ip it will just fail.

This setting can be used to configure MonogDB process to bind to and listen for connections from applications on this address. If not specified, the module will use the default for your OS distro. Note: This value should be passed as an array.

When manage_package_repo is set to true, this setting indicates if it will use the Community Edition (false, the default) or the Enterprise one (true).

The version of MonogDB to install/manage. This is needed when managing repositories. If not specified, the module will use the default for your OS distro.

This setting can be used to override the default MongoDB repository location. If not specified, the module will use the default repository for your OS distro.

This will allow you to set a proxy for your repository in case you are behind a corporate firewall. Currently this is only supported with yum repositories

This sets the username for the proxyserver, should authentication be required

This sets the password for the proxyserver, should authentication be required

Most of the parameters manipulate the mongod.conf file.

For more details about configuration parameters consult the MongoDB Configuration File Options.

Used to ensure that the package is installed and the service is running, or that the package is absent/purged and the service is stopped. Valid values are true/false/present/absent/purged.

Path of the config file. If not specified, the module will use the default for your OS distro.

Set this value to designate a directory for the mongod instance to store it's data. If not specified, the module will use the default for your OS distro.

Set this value to true if you want puppet to recursively manage the permissions of the files in the dbpath directory. If you are using the default dbpath, this should probably be false. Set this to true if you are using a custom dbpath. The default is false.

Specify a file location to hold the PID or process ID of the mongod process. If not specified, the module will use the default for your OS distro.

Should puppet create the pidfile. Mondod 6.2.10 will not start if pidfile exists

Specify the path to a file name for the log file that will hold all diagnostic logging information. Unless specified, mongod will output all log information to the standard output.

This setting has to be true to configure MongoDB to turn on ipv6 support. If not specified and ipv6 address is passed to MongoDB bind_ip it will just fail.

Set this option to configure the mongod or mongos process to bind to and listen for connections from applications on this address. If not specified, the module will use the default for your OS distro. Example: bind_ip=['127.0.0.1', '192.168.0.3'] Note: bind_ip accepts an array as a value.

Set to true to add new entries to the end of the logfile rather than overwriting the content of the log when the process restarts. Default: True

Set to reopen for mongo to close a log file then reopen it so that logrotations handled outside of mongo perform as expected. Default: undef

Set to true to fork server process at launch time. The default setting depends on the operating system.

Specifies a TCP port for the server instance to listen for client connections. Default: 27017

Set to true to enable operation journaling to ensure write durability and data consistency. Default: on 64-bit systems true and on 32-bit systems false

Set nojournal = true to disable durability journaling. By default, mongod enables journaling in 64-bit versions after v2.0. Default: on 64-bit systems false and on 32-bit systems true

Note: You must use journal to enable journaling on 32-bit systems.

Set to true to modify MongoDB to use a smaller default data file size. Specifically, smallfiles reduces the initial size for data files and limits them to 512 megabytes. Default: false

Set to true to force mongod to report every four seconds CPU utilization and the amount of time that the processor waits for I/O operations to complete (i.e. I/O wait.) Default: false

Set to true to enable database authentication for users connecting from remote hosts. If no users exist, the localhost interface will continue to have access to the database until you create the first user. Default: false

Disable authentication. Currently the default. Exists for future compatibility and clarity.

Increases the amount of internal reporting returned on standard output or in the log file generated by logpath. Default: false

MongoDB has the following levels of verbosity: v, vv, vvv, vvvv and vvvvv. Default: None

Forces the mongod to validate all requests from clients upon receipt to ensure that clients never insert invalid documents into the database.

Set to true to enable a maximum limit for the number of data files each database can have. The default quota is 8 data files, when quota is true. Default: false

Modify limit on the number of data files per database. This option requires the quota setting. Default: 8

Creates a very verbose diagnostic log for troubleshooting and recording various errors. Valid values: 0, 1, 2, 3 and 7. For more information please refer to MongoDB Configuration File Options.

Set to true to modify the storage pattern of the data directory to store each database’s files in a distinct folder. Default: false

Modify this value to changes the level of database profiling, which inserts information about operation performance into output of mongod or the log file if specified by logpath.

Specifies a value to set the maximum number of simultaneous connections that MongoDB will accept. Default: depends on system (i.e. ulimit and file descriptor) limits. Unless set, MongoDB will not limit its own connections.

Specifies a maximum size in megabytes for the replication operation log (e.g. oplog.) mongod creates an oplog based on the maximum amount of space available. For 64-bit systems, the oplog is typically 5% of available disk space.

Ignore query hints. Default: None

Set to true to disable the HTTP interface. This command will override the rest and disable the HTTP interface if you specify both. Default: false

Set noscripting = true to disable the scripting engine. Default: false

Set notablescan = true to forbid operations that require a table scan. Default: false

Set noprealloc = true to disable the preallocation of data files. This will shorten the start up time in some cases, but can cause significant performance penalties during normal operations. Default: false

Use this setting to control the default size for all newly created namespace files (i.e .ns). Default: 16

MMS token for mms monitoring. Default: None

MMS identifier for mms monitoring. Default: None

MMS interval for mms monitoring. Default: None

Use this setting to enable config server mode for mongod.

Use this setting to enable shard server mode for mongod.

Use this setting to configure replication with replica sets. Specify a replica set name as an argument to this set. All hosts must have the same set name.

An array of member hosts for the replica set. Mutually exclusive with replset_config param.

A hash that is used to configure the replica set. Mutually exclusive with replset_members param.

class mongodb::server {
  replset        => 'rsmain',
  replset_config => { 'rsmain' => { ensure  => present, settings => { heartbeatTimeoutSecs => 15, getLastErrorModes => { ttmode => { dc => 1 } } }, members => [{'host'=>'host1:27017', 'tags':{ 'dc' : 'east'}}, { 'host' => 'host2:27017'}, 'host3:27017']  }  }

}

A hash to allow for additional configuration options to be set in user-provided template.

Set to true to enable a simple REST interface. Default: false

Runs the mongod or mongos instance in a quiet mode that attempts to limit the amount of output. This option suppresses : "output from database commands, including drop, dropIndexes, diagLogging, validate, and clean", "replication activity", "connection accepted events" and "connection closed events". Default: false

For production systems this option is not recommended as it may make tracking problems during particular connections much more difficult.

Sets the threshold for mongod to consider a query “slow” for the database profiler. Default: 100 ms

Specify the path to a key file to store authentication information. This option is only useful for the connection between replica set members. Default: None

Specify the key contained within the keyfile. This option is only useful for the connection between replica set members. Default: None

Set to true to configure the current instance to act as master instance in a replication configuration. Default: False Note: deprecated – use replica sets

Specify extra configuration file parameters (i.e. textSearchEnabled=true). Default: None

Sends all logging output to the host’s syslog system rather than to standard output or a log file. Default: None Important: You cannot use syslog with logpath. Set logpath to false to disable it.

Set to true to configure the current instance to act as slave instance in a replication configuration. Default: false Note: deprecated – use replica sets

Used with the slave option, only specifies only a single database to replicate. Default: <> Note: deprecated – use replica sets

Used with the slave setting to specify the master instance from which this slave instance will replicate. Default: <> Note: deprecated – use replica sets

Set to true to enable ssl. Default: <> Important: You need to have ssl_key set as well, and the file needs to pre-exist on node. If you wish to use certificate validation, ssl_ca must also be set.

Default: <>

Default: <>

Set to true to disable mandatory SSL client authentication Default: False

Set to true to disable fqdn SSL cert check Default: False

Ssl authorization mode. Valid options are: requireSSL, preferSSL, allowSSL. Default: requireSSL

Set to true to enable tls. Default: <> Important: You need to have tls_key set as well, and the file needs to pre-exist on node. If you wish to use certificate validation, tls_ca must also be set.

Default: <>

Default: <>

Set to true to disable mandatory TLS client authentication Default: False

Set to true to disable fqdn TLS cert check Default: False

Tls authorization mode. Valid options are: requireTLS, preferTLS, allowTLS. Default: requireTLS

Whether or not the MongoDB service resource should be part of the catalog. Default: true

Only needed for MongoDB 3.x versions, where it's possible to select the 'wiredTiger' engine in addition to the default 'mmapv1' engine. If not set, the config is left out and mongo will default to 'mmapv1'. You should not set this for MongoDB versions < 3.x

Specifies whether the service should be restarted on config changes. Default: 'true'

Allows to create admin user for admin database. Redefine these parameters if needed:

Administrator user name

Administrator user password

Administrator authentication mechanism. scram_sha_256 password synchronization verification is not supported. Default: 'scram_sha_1'

Update password. Used with SCRAM-SHA-256 because password verification is not supported. Default: false

Administrator user roles

Store admin credentials in mongorc.js file. Uses with create_admin parameter

Set this to false to avoid having puppet handle .mongorc.js in case you wish to deliver it by other means. This is needed for facts to work if you have auth set to true. Default is true.

class. This class should only be used if you want to implement sharding within your mongodb deployment.

This class allows you to configure the mongos daemon (responsible for routing) on your platform.

Used to ensure that the package is installed and the service is running, or that the package is absent/purged and the service is stopped. Valid values are true/false/present/absent/purged.

Path of the config file. If not specified, the module will use the default for your OS distro.

Config content if the default doesn't match one needs.

Path to the config template if the default doesn't match one needs.

Hash containing key-value pairs to allow for additional configuration options to be set in user-provided template.

Array of the config servers IP addresses the mongos should connect to.

Whether or not the MongoDB sharding service resource should be part of the catalog. Default: true

This setting can be used to override the default Mongos service name. If not specified, the module will use whatever service name is the default for your OS distro.

This setting can be used to override the default Mongos service provider. If not specified, the module will use whatever service provider is the default for your OS distro.

This setting can be used to override the default status check command for your Mongos service. If not specified, the module will use whatever service name is the default for your OS distro.

This setting can be used to specify if the service should be enable at boot

This setting can be used to specify if the service should be running

This setting can be used to specify if puppet should install the package or not

This setting can be used to specify the name of the package that should be installed. If not specified, the module will use whatever service name is the default for your OS distro.

Specifies whether the service should be restarted on config changes. Default: 'true'

Creates database with user. Resource title used as database name.

Name of the user for database

Hex encoded md5 hash of "$username:mongo:$password". For more information please refer to MongoDB Authentication Process.

Plain-text user password (will be hashed)

Authentication mechanism. Can be either 'scram_sha_1' or 'scram_sha_256'. scram_sha_256 password synchronization verification is not supported. Default: 'scram_sha_1'

Update password. Used with SCRAM-SHA-256 because password verification is not supported. Default: false

Array with user roles as string. Roles will be granted to user's database if no alternative database is explicitly defined. Example: ['dbAdmin', 'readWrite@other_database'] Default: ['dbAdmin']

'mongodb_database' can be used to create and manage databases within MongoDB.

mongodb_database { testdb:
  ensure   => present,
  tries    => 10,
  require  => Class['mongodb::server'],
}

The maximum amount of two second tries to wait MongoDB startup. Default: 10

'mongodb_user' can be used to create and manage users within MongoDB database.

Note: if replica set is enabled, replica initialization has to come before any user operations.

mongodb_user { testuser:
  name          => 'testuser',
  ensure        => present,
  password_hash => mongodb_password('testuser', 'p@ssw0rd'),
  database      => testdb,
  roles         => ['readWrite', 'dbAdmin'],
  tries         => 10,
  require       => Class['mongodb::server'],
}

Name of the mongodb user.

Hex encoded md5 hash of "$username:mongo:$password". Only available on MongoDB 3.0 and later.

Plaintext password of the user.

Name of database. It will be created, if not exists.

Array with user roles as string. Roles will be granted to user's database if no alternative database is explicitly defined. Example: ['dbAdmin', 'readWrite@other_database'] Default: ['dbAdmin']

The maximum amount of two second tries to wait MongoDB startup. Default: 10

'mongodb_replset' can be used to create and manage MongoDB replicasets.

mongodb_replset { rsmain:
  ensure  => present,
  members => ['host1:27017', 'host2:27017', 'host3:27017']
}

Ideally the mongodb_replset resource will be declared on the initial desired primary node (arbitrarily the first of the list) and this node will be processed once the secondary nodes are up. This will ensure all the nodes are in the first configuration of the replicaset, else it will require running puppet again to add them.

Array of 'host:port' of the replicaset members.

It currently only adds members without options.

'mongodb_shard' can be used to create and manage MongoDB shards. Note: Removing a shard is not yet supported. Shard can only be added.

mongodb_shard { 'rsmain':
  member => 'rsmain/host1:27017',
  keys   => [{'rsmain.foo' => {'name' => 1}}],
}

Member of the shard in the form;

• hostname
• [replica-set-name]/hostname
• [replica-set-name]/hostname:port

Sharding keys for a specific database. This variable should be an array of sharding keys.

This module has been tested on:

• Debian 7.* (Wheezy)
• Debian 6.* (squeeze)
• Ubuntu 12.04.2 (precise)
• Ubuntu 10.04.4 LTS (lucid)
• RHEL 5/6/7
• CentOS 5/6/7

For a full list of tested operating systems please have a look at the .nodeset.xml definition.

This module should support service_ensure separate from the ensure value on Class[mongodb::server] but it does not yet.

While this module supports both 1.x and 2.x versions of the puppetlabs-apt module, it does not support puppetlabs-apt 2.0.0 or 2.0.1.

This module is maintained by Vox Pupuli. Voxpupuli welcomes new contributions to this module, especially those that include documentation and rspec tests. We are happy to provide guidance if necessary.

Please see CONTRIBUTING for more details.

• Puppetlabs Module Team
• Voxpupuli Team

We would like to thank everyone who has contributed issues and pull requests to this module. A complete list of contributors can be found on the GitHub Contributor Graph for the puppet-mongodb module.