MongoDB
view release on metacpan or search on metacpan
- The v1.0.0 driver includes numerous incompatible changes; users are
STRONGLY encouraged to read MongoDB::Upgrading for advice on upgrading
applications written for the 'v0' driver.
- PERL-221 The 'inflate_regexps' MongoDB::MongoClient option has been
removed. BSON regular expressions always decode to
MongoDB::BSON::Regexp objects. This ensure safety and consistency with
other drivers.
- PERL-330 The driver now uses pure-Perl networking; SSL and SASL now
implemented via optional CPAN modules IO::Socket::SSL and Authen::SASL.
- PERL-442 Connection string options have revised to match MongoClient
options; connection string options always take precedence over
MongoClient constructor arguments.
- PERL-470 The MongoDB::Cursor globals "slave_ok" and "timeout" no longer
have any effect and have been removed.
- PERL-471 The MongoDB::Cursor 'snapshot' method now requires a boolean
argument.
'$MongoDB::BSON::char' have been deprecated in addition to their other
behavior changes.
[Additions]
- PERL-93 Implemented awaitData cursor support.
- PERL-135 Added the ability to set write_concern at database and
collection level, rather than only in MongoDB::MongoClient.
- PERL-233 Implemented SSL certificate support via IO::Socket::SSL
options.
- PERL-375 Added support for cursor options to the MongoDB::Collection
'find_one' method.
- PERL-378 Implemented the cross-driver Server Discovery and Monitoring
specification.
- PERL-379 Implemented the cross-driver Server Selection specification.
## Installing from the git repository
If you have checked out the git repository (or downloaded a tarball from
Github), you will need to install configuration requirements and follow the
manual procedure described above.
## SSL and/or SASL support
SSL support requires installing the
[IO::Socket::SSL](http://p3rl.org/IO::Socket::SSL) module. You will need
to have the libssl-dev package or equivalent installed for that to build
successfully.
SASL support requires [Authen::SASL](http://p3rl.org/Authen::SASL) and
possibly a Kerberos-capable backend.
The [Authen::SASL::Perl](http://p3rl.org/Authen::SASL::Perl) backend comes
with Authen::SASL and requires the [GSSAPI](http://p3rl.org/GSSAPI) CPAN
module for GSSAPI support.
"Test::Perl::Critic" : "0",
"Test::Pod" : "1.41",
"Test::Spelling" : "0.12",
"Test::Version" : "1",
"lib" : "0"
}
},
"runtime" : {
"recommends" : {
"IO::Socket::IP" : "0.32",
"IO::Socket::SSL" : "1.42",
"Mozilla::CA" : "20130114",
"Net::SSLeay" : "1.49"
},
"requires" : {
"Authen::SASL::SASLprep" : "0",
"Authen::SCRAM::Client" : "0.011",
"BSON" : "1.012000",
"BSON::Bytes" : "0",
"BSON::Code" : "0",
"BSON::DBRef" : "0",
"if" : "0",
"namespace::clean" : "0",
"overload" : "0",
"perl" : "5.010001",
"re" : "0",
"strict" : "0",
"version" : "0",
"warnings" : "0"
},
"suggests" : {
"IO::Socket::SSL" : "1.56"
}
},
"test" : {
"recommends" : {
"CPAN::Meta" : "2.120900",
"Test::Harness" : "3.31",
"Time::Moment" : "0.22"
},
"requires" : {
"BSON::Decimal128" : "0",
file: lib/MongoDB/WriteConcern.pm
version: v2.2.2
MongoDB::WriteConcernError:
file: lib/MongoDB/Error.pm
version: v2.2.2
MongoDB::WriteError:
file: lib/MongoDB/Error.pm
version: v2.2.2
recommends:
IO::Socket::IP: '0.32'
IO::Socket::SSL: '1.42'
Mozilla::CA: '20130114'
Net::SSLeay: '1.49'
requires:
Authen::SASL::SASLprep: '0'
Authen::SCRAM::Client: '0.011'
BSON: '1.012000'
BSON::Bytes: '0'
BSON::Code: '0'
BSON::DBRef: '0'
BSON::OID: '0'
lib/MongoDB/MongoClient.pm view on Meta::CPAN
);
}
#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
lib/MongoDB/MongoClient.pm view on Meta::CPAN
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
lib/MongoDB/MongoClient.pm view on Meta::CPAN
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:
lib/MongoDB/MongoClient.pm view on Meta::CPAN
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",
lib/MongoDB/Upgrading/v1.pod view on Meta::CPAN
=head2 Moo instead of Moose
The v1 driver uses L<Moo> instead of L<Moose>. This change results in
a slightly faster driver and a significantly reduced deep dependency tree.
=head2 SSL and SASL
The v0 driver required a compiler and OpenSSL and libgsasl for SSL and SASL
support, respectively. The v1 driver instead relies on CPAN modules
C<IO::Socket::SSL> and C<Authen::SASL> for SSL and SASL support,
respectively.
SSL configuration is now possible via the L<ssl
attribute|MongoDB::MongoClient/ssl>.
Authentication configuration is described in L<MongoDB::MongoClient/AUTHENTICATION>.
=head1 BEHAVIOR CHANGES
=head2 MongoClient configuration
lib/MongoDB/_Link.pm view on Meta::CPAN
return $hr;
};
sub connect {
@_ == 1 || MongoDB::UsageError->throw( q/Usage: $handle->connect()/ . "\n" );
my ($self) = @_;
if ( $self->with_ssl ) {
$self->_assert_ssl;
# XXX possibly make SOCKET_CLASS an instance variable and set it here to IO::Socket::SSL
}
my ($host, $port) = split /:/, $self->address;
# PERL-715: For 'localhost' where MongoDB is only listening on IPv4 and
# getaddrinfo returns an IPv6 address before an IPv4 address, some
# operating systems tickle a bug in IO::Socket::IP that causes
# connection attempts to fail before trying the IPv4 address. As a
# workaround, we always force 'localhost' to use IPv4.
lib/MongoDB/_Link.pm view on Meta::CPAN
my ( $self, $version ) = @_;
my $min = $self->min_wire_version || 0;
my $max = $self->max_wire_version || 0;
return $version >= $min && $version <= $max;
}
sub start_ssl {
my ( $self, $host ) = @_;
my $ssl_args = $self->_ssl_args($host);
IO::Socket::SSL->start_SSL(
$self->fh,
%$ssl_args,
SSL_create_ctx_callback => sub {
my $ctx = shift;
Net::SSLeay::CTX_set_mode( $ctx, Net::SSLeay::MODE_AUTO_RETRY() );
},
);
unless ( ref( $self->fh ) eq 'IO::Socket::SSL' ) {
my $ssl_err = IO::Socket::SSL->errstr;
$self->_close;
MongoDB::HandshakeError->throw(qq/SSL connection failed for $host: $ssl_err\n/);
}
}
sub client_certificate_subject {
my ($self) = @_;
return "" unless $self->fh && $self->fh->isa("IO::Socket::SSL");
my $client_cert = $self->fh->sock_certificate()
or return "";
my $subject_raw = Net::SSLeay::X509_get_subject_name($client_cert)
or return "";
my $subject =
Net::SSLeay::X509_NAME_print_ex( $subject_raw, Net::SSLeay::XN_FLAG_RFC2253() );
lib/MongoDB/_Link.pm view on Meta::CPAN
}
last unless length($msg) < $len;
}
$self->_set_last_used(time);
return $msg;
}
sub _assert_ssl {
# Need IO::Socket::SSL 1.42 for SSL_create_ctx_callback
MongoDB::UsageError->throw(qq/IO::Socket::SSL 1.42 must be installed for SSL support\n/)
unless eval { require IO::Socket::SSL; IO::Socket::SSL->VERSION(1.42) };
# Need Net::SSLeay 1.49 for MODE_AUTO_RETRY
MongoDB::UsageError->throw(qq/Net::SSLeay 1.49 must be installed for SSL support\n/)
unless eval { require Net::SSLeay; Net::SSLeay->VERSION(1.49) };
}
# Try to find a CA bundle to validate the SSL cert,
# prefer Mozilla::CA or fallback to a system file
sub _find_CA_file {
my $self = shift();
lib/MongoDB/_Link.pm view on Meta::CPAN
MongoDB::UsageError->throw(
qq/Couldn't find a CA bundle with which to verify the SSL certificate.\n/
. qq/Try installing Mozilla::CA from CPAN\n/);
}
sub _ssl_args {
my ( $self, $host ) = @_;
my %ssl_args;
# This test reimplements IO::Socket::SSL::can_client_sni(), which wasn't
# added until IO::Socket::SSL 1.84
if ( Net::SSLeay::OPENSSL_VERSION_NUMBER() >= 0x10000000 ) {
$ssl_args{SSL_hostname} = $host, # Sane SNI support
}
if ( Net::SSLeay::OPENSSL_VERSION_NUMBER() >= 0x10100000 ) {
$ssl_args{SSL_OP_NO_RENEGOTIATION} = Net::SSLeay::OP_NO_RENEGOTIATION();
}
$ssl_args{SSL_verifycn_scheme} = 'http'; # enable CN validation
$ssl_args{SSL_verifycn_name} = $host; # set validation hostname
t/00-report-prereqs.dd view on Meta::CPAN
'Test::Perl::Critic' => '0',
'Test::Pod' => '1.41',
'Test::Spelling' => '0.12',
'Test::Version' => '1',
'lib' => '0'
}
},
'runtime' => {
'recommends' => {
'IO::Socket::IP' => '0.32',
'IO::Socket::SSL' => '1.42',
'Mozilla::CA' => '20130114',
'Net::SSLeay' => '1.49'
},
'requires' => {
'Authen::SASL::SASLprep' => '0',
'Authen::SCRAM::Client' => '0.011',
'BSON' => '1.012000',
'BSON::Bytes' => '0',
'BSON::Code' => '0',
'BSON::DBRef' => '0',
t/00-report-prereqs.dd view on Meta::CPAN
'if' => '0',
'namespace::clean' => '0',
'overload' => '0',
'perl' => '5.010001',
're' => '0',
'strict' => '0',
'version' => '0',
'warnings' => '0'
},
'suggests' => {
'IO::Socket::SSL' => '1.56'
}
},
'test' => {
'recommends' => {
'CPAN::Meta' => '2.120900',
'Test::Harness' => '3.31',
'Time::Moment' => '0.22'
},
'requires' => {
'BSON::Decimal128' => '0',
( run in 0.413 second using v1.01-cache-2.11-cpan-fd5d4e115d8 )