MongoDB
view release on metacpan or search on metacpan
lib/MongoDB/MongoClient.pm view on Meta::CPAN
has socket_check_interval_ms => (
is => 'lazy',
isa => NonNegNum,
builder => '_build_socket_check_interval_ms',
);
sub _build_socket_check_interval_ms {
my ($self) = @_;
return $self->__uri_or_else(
u => 'socketcheckintervalms',
e => 'socket_check_interval_ms',
d => 5000,
);
}
#pod =attr socket_timeout_ms
#pod
#pod This attribute specifies the amount of time in milliseconds to wait for a
#pod reply from the server before issuing a network exception.
#pod
#pod The default is 30,000 ms.
#pod
#pod If set to a negative value, socket operations will block indefinitely
#pod until the server replies or until the operating system TCP/IP stack
#pod gives up.
#pod
#pod The driver automatically sets the TCP keepalive option when initializing the
#pod socket. For keepalive related issues, check the MongoDB documentation for
#pod L<Does TCP keepalive time affect MongoDB Deployments?|https://docs.mongodb.com/v3.2/faq/diagnostics/#does-tcp-keepalive-time-affect-mongodb-deployments>.
#pod
#pod A zero value polls the socket for available data and is thus likely to fail
#pod except when talking to a local process (and perhaps even then).
#pod
#pod This may be set in a connection string with the C<socketTimeoutMS> option.
#pod
#pod =cut
has socket_timeout_ms => (
is => 'lazy',
isa => Num,
builder => '_build_socket_timeout_ms',
);
sub _build_socket_timeout_ms {
my ($self) = @_;
return $self->__uri_or_else(
u => 'sockettimeoutms',
e => 'socket_timeout_ms',
d => 30000,
);
}
#pod =attr ssl
#pod
#pod ssl => 1
#pod ssl => \%ssl_options
#pod
#pod This tells the driver that you are connecting to an SSL mongodb instance.
#pod
#pod You must have L<IO::Socket::SSL> 1.42+ and L<Net::SSLeay> 1.49+ installed for
#pod SSL support.
#pod
#pod The C<ssl> attribute takes either a boolean value or a hash reference of
#pod options to pass to IO::Socket::SSL. For example, to set a CA file to validate
#pod the server certificate and set a client certificate for the server to validate,
#pod you could set the attribute like this:
#pod
#pod ssl => {
#pod SSL_ca_file => "/path/to/ca.pem",
#pod SSL_cert_file => "/path/to/client.pem",
#pod }
#pod
#pod If C<SSL_ca_file> is not provided, server certificates are verified against a
#pod default list of CAs, either L<Mozilla::CA> or an operating-system-specific
#pod default CA file. To disable verification, you can use
#pod C<< SSL_verify_mode => 0x00 >>.
#pod
#pod B<You are strongly encouraged to use your own CA file for increased security>.
#pod
#pod Server hostnames are also validated against the CN name in the server
#pod certificate using C<< SSL_verifycn_scheme => 'http' >>. You can use the
#pod scheme 'none' to disable this check.
#pod
#pod B<Disabling certificate or hostname verification is a security risk and is not
#pod recommended>.
#pod
#pod This may be set to the string 'true' or 'false' in a connection string with the
#pod C<ssl> option, which will enable ssl with default configuration. (See
#pod L<connection string URI|/CONNECTION STRING URI> for additional TLS
#pod configuration options.)
#pod
#pod =cut
has ssl => (
is => 'lazy',
isa => Boolish|HashRef,
builder => '_build_ssl',
);
sub _build_ssl {
my ($self) = @_;
# options will be undef if not provided
my $uri_ssl = $self->__ssl_from_uri();
my $opt_ssl = exists $self->_deferred->{ssl} ? $self->_deferred->{ssl} : undef;
# no SSL options exist
if ( !defined $uri_ssl && !defined $opt_ssl ) {
return 0;
}
# validate deferred ssl arg type
if ( ref $opt_ssl && ref $opt_ssl ne 'HASH' ) {
MongoDB::UsageError->throw("ssl attribute must be scalar or hashref")
}
# no URI SSL defined means use opts SSL
if ( !defined $uri_ssl ) {
return $opt_ssl;
}
# if URI SSL is false, that takes precedence
if ( ! $uri_ssl ) {
return $uri_ssl;
lib/MongoDB/MongoClient.pm view on Meta::CPAN
When true, the client will B<not> use the C<server_selection_timeout_ms>.
Instead, if the topology information is stale and needs to be checked or
if no suitable server is available, the client will make a single
scan of all known servers to try to find a suitable one.
When false, the client will continually scan known servers until a suitable
server is found or the C<serverSelectionTimeoutMS> is reached.
See L</SERVER SELECTION> for more details.
This may be set in a connection string with the C<serverSelectionTryOnce>
option.
=head2 server_selector
Optional. This takes a function that augments the server selection rules.
The function takes as a parameter a list of server descriptions representing
the suitable servers for the read or write operation, and returns a list of
server descriptions that should still be considered suitable. Most users
should rely on the default server selection algorithm and should not need
to set this attribute.
=head2 socket_check_interval_ms
If a socket to a server has not been used in this many milliseconds, an
C<ismaster> command will be issued to check the status of the server before
issuing any reads or writes. Must be non-negative.
The default is 5,000 ms.
This may be set in a connection string with the C<socketCheckIntervalMS>
option.
=head2 socket_timeout_ms
This attribute specifies the amount of time in milliseconds to wait for a
reply from the server before issuing a network exception.
The default is 30,000 ms.
If set to a negative value, socket operations will block indefinitely
until the server replies or until the operating system TCP/IP stack
gives up.
The driver automatically sets the TCP keepalive option when initializing the
socket. For keepalive related issues, check the MongoDB documentation for
L<Does TCP keepalive time affect MongoDB Deployments?|https://docs.mongodb.com/v3.2/faq/diagnostics/#does-tcp-keepalive-time-affect-mongodb-deployments>.
A zero value polls the socket for available data and is thus likely to fail
except when talking to a local process (and perhaps even then).
This may be set in a connection string with the C<socketTimeoutMS> option.
=head2 ssl
ssl => 1
ssl => \%ssl_options
This tells the driver that you are connecting to an SSL mongodb instance.
You must have L<IO::Socket::SSL> 1.42+ and L<Net::SSLeay> 1.49+ installed for
SSL support.
The C<ssl> attribute takes either a boolean value or a hash reference of
options to pass to IO::Socket::SSL. For example, to set a CA file to validate
the server certificate and set a client certificate for the server to validate,
you could set the attribute like this:
ssl => {
SSL_ca_file => "/path/to/ca.pem",
SSL_cert_file => "/path/to/client.pem",
}
If C<SSL_ca_file> is not provided, server certificates are verified against a
default list of CAs, either L<Mozilla::CA> or an operating-system-specific
default CA file. To disable verification, you can use
C<< SSL_verify_mode => 0x00 >>.
B<You are strongly encouraged to use your own CA file for increased security>.
Server hostnames are also validated against the CN name in the server
certificate using C<< SSL_verifycn_scheme => 'http' >>. You can use the
scheme 'none' to disable this check.
B<Disabling certificate or hostname verification is a security risk and is not
recommended>.
This may be set to the string 'true' or 'false' in a connection string with the
C<ssl> option, which will enable ssl with default configuration. (See
L<connection string URI|/CONNECTION STRING URI> for additional TLS
configuration options.)
=head2 username
Optional username for this client connection. If this field is set, the client
will attempt to authenticate when connecting to servers. Depending on the
L</auth_mechanism>, the L</password> field or other attributes will need to be
set for authentication to succeed.
This may be provided in the L<connection string URI|/CONNECTION STRING URI> as
a C<username:password> pair in the leading portion of the authority section
before a C<@> character. For example, to authenticate as user "mulder" with
password "trustno1":
mongodb://mulder:trustno1@localhost
If the username or password have a ":" or "@" in it, they must be URL encoded.
An empty password still requires a ":" character.
=head2 w
The client I<write concern>.
=over 4
=item * C<0> Unacknowledged. MongoClient will B<NOT> wait for an acknowledgment that
the server has received and processed the request. Older documentation may refer
to this as "fire-and-forget" mode. This option is not recommended.
=item * C<1> Acknowledged. MongoClient will wait until the
primary MongoDB acknowledges the write.
=item * C<2> Replica acknowledged. MongoClient will wait until at least two
replicas (primary and one secondary) acknowledge the write. You can set a higher
number for more replicas.
lib/MongoDB/MongoClient.pm view on Meta::CPAN
If a suitable server is not immediately available, what happens next
depends on the L</server_selection_try_once> option.
If that option is true, a single topology scan will be performed.
Afterwards if a suitable server is available, it will be returned;
otherwise, an exception is thrown.
If that option is false, the driver will do topology scans repeatedly
looking for a suitable server. When more than
L</server_selection_timeout_ms> milliseconds have elapsed since the start
of server selection without a suitable server being found, an exception is
thrown.
B<Note>: the actual maximum wait time for server selection could be as long
C<server_selection_timeout_ms> plus the amount of time required to do a
topology scan.
=head1 SERVER MONITORING AND FAILOVER
When the client first needs to find a server for a database operation, all
servers from the L</host> attribute are scanned to determine which servers to
monitor. If the deployment is a replica set, additional hosts may be
discovered in this process. Invalid hosts are dropped.
After the initial scan, whenever the servers have not been checked in
L</heartbeat_frequency_ms> milliseconds, the scan will be repeated. This
amortizes monitoring time over many of operations. Additionally, if a
socket has been idle for a while, it will be checked before being used for
an operation.
If a server operation fails because of a "not master" or "node is
recovering" error, or if there is a network error or timeout, then the
server is flagged as unavailable and exception will be thrown. See
L<MongoDB::Errors> for exception types.
If the error is caught and handled, the next operation will rescan all
servers immediately to update its view of the topology. The driver can
continue to function as long as servers are suitable per L</SERVER
SELECTION>.
When catching an exception, users must determine whether or not their
application should retry an operation based on the specific operation
attempted and other use-case-specific considerations. For automating
retries despite exceptions, consider using the L<Try::Tiny::Retry> module.
=head1 TRANSPORT LAYER SECURITY
B<Warning>: industry best practices, and some regulations, require the use
of TLS 1.1 or newer.
Some operating systems or versions may not provide an OpenSSL version new
enough to support the latest TLS protocols. If your OpenSSL library
version number is less than 1.0.1, then support for TLS 1.1 or newer is not
available. Contact your operating system vendor for a solution or upgrade
to a newer operating system distribution.
See also the documentation for L<Net::SSLeay> for details on installing and
compiling against OpenSSL.
TLS connections in the driver rely on the default settings provided by
L<IO::Socket::SSL>, but allow you to pass custom configuration to it.
Please read its documentation carefully to see how to control your TLS
configuration.
=head1 AUTHENTICATION
The MongoDB server provides several authentication mechanisms, though some
are only available in the Enterprise edition.
MongoDB client authentication is controlled via the L</auth_mechanism>
attribute, which takes one of the following values:
B<NOTE>: MONGODB-CR was deprecated with the release of MongoDB 3.6 and
is no longer supported by MongoDB 4.0.
=over 4
=item *
MONGODB-CR -- legacy username-password challenge-response (< 4.0)
=item *
SCRAM-SHA-1 -- secure username-password challenge-response (3.0+)
=item *
MONGODB-X509 -- SSL client certificate authentication (2.6+)
=item *
PLAIN -- LDAP authentication via SASL PLAIN (Enterprise only)
=item *
GSSAPI -- Kerberos authentication (Enterprise only)
=back
The mechanism to use depends on the authentication configuration of the
server. See the core documentation on authentication:
L<http://docs.mongodb.org/manual/core/access-control/>.
Usage information for each mechanism is given below.
=head2 MONGODB-CR and SCRAM-SHA-1 (for username/password)
These mechanisms require a username and password, given either as
constructor attributes or in the C<host> connection string.
If a username is provided and an authentication mechanism is not specified,
the client will use SCRAM-SHA-1 for version 3.0 or later servers and will
fall back to MONGODB-CR for older servers.
my $mc = MongoDB::MongoClient->new(
host => "mongodb://mongo.example.com/",
username => "johndoe",
password => "trustno1",
);
my $mc = MongoDB::MongoClient->new(
host => "mongodb://johndoe:trustno1@mongo.example.com/",
);
Usernames and passwords will be UTF-8 encoded before use. The password is
never sent over the wire -- only a secure digest is used. The SCRAM-SHA-1
mechanism is the Salted Challenge Response Authentication Mechanism
defined in L<RFC 5802|http://tools.ietf.org/html/rfc5802>.
The default database for authentication is 'admin'. If another database
name should be used, specify it with the C<db_name> attribute or via the
connection string.
db_name => auth_db
mongodb://johndoe:trustno1@mongo.example.com/auth_db
=head2 MONGODB-X509 (for SSL client certificate)
X509 authentication requires SSL support (L<IO::Socket::SSL>), requires
that a client certificate be configured in the ssl parameters, and requires
specifying the "MONGODB-X509" authentication mechanism.
my $mc = MongoDB::MongoClient->new(
host => "mongodb://sslmongo.example.com/",
ssl => {
SSL_ca_file => "certs/ca.pem",
SSL_cert_file => "certs/client.pem",
},
auth_mechanism => "MONGODB-X509",
);
B<Note>: Since MongoDB Perl driver v1.8.0, you no longer need to specify a
C<username> parameter for X509 authentication; the username will be
extracted automatically from the certificate.
=head2 PLAIN (for LDAP)
This mechanism requires a username and password, which will be UTF-8
encoded before use. The C<auth_mechanism> parameter must be given as a
constructor attribute or in the C<host> connection string:
my $mc = MongoDB::MongoClient->new(
host => "mongodb://mongo.example.com/",
username => "johndoe",
password => "trustno1",
auth_mechanism => "PLAIN",
);
my $mc = MongoDB::MongoClient->new(
host => "mongodb://johndoe:trustno1@mongo.example.com/authMechanism=PLAIN",
);
=head2 GSSAPI (for Kerberos)
Kerberos authentication requires the CPAN module L<Authen::SASL> and a
GSSAPI-capable backend.
On Debian systems, L<Authen::SASL> may be available as
C<libauthen-sasl-perl>; on RHEL systems, it may be available as
C<perl-Authen-SASL>.
The L<Authen::SASL::Perl> backend comes with L<Authen::SASL> and requires
the L<GSSAPI> CPAN module for GSSAPI support. On Debian systems, this may
be available as C<libgssapi-perl>; on RHEL systems, it may be available as
C<perl-GSSAPI>.
Installing the L<GSSAPI> module from CPAN rather than an OS package
requires C<libkrb5> and the C<krb5-config> utility (available for
Debian/RHEL systems in the C<libkrb5-dev> package).
Alternatively, the L<Authen::SASL::XS> or L<Authen::SASL::Cyrus> modules
may be used. Both rely on Cyrus C<libsasl>. L<Authen::SASL::XS> is
preferred, but not yet available as an OS package. L<Authen::SASL::Cyrus>
is available on Debian as C<libauthen-sasl-cyrus-perl> and on RHEL as
C<perl-Authen-SASL-Cyrus>.
Installing L<Authen::SASL::XS> or L<Authen::SASL::Cyrus> from CPAN requires
C<libsasl>. On Debian systems, it is available from C<libsasl2-dev>; on
RHEL, it is available in C<cyrus-sasl-devel>.
( run in 2.070 seconds using v1.01-cache-2.11-cpan-39bf76dae61 )