Getting Started: Configuring a Domain
A while ago I wrote an entry here on how get started with NuoDB by provisioning a domain. Most of that focused on what a domain is, how to get a couple of hosts online and working together and how to use the command-line to manage those hosts. Since then I’ve heard a lot of interest for a follow-on piece that talks about what to do after you’ve got the basic install done.
NuoDB is designed to be pretty simple to get running out of the box. After you’ve kicked the tires, walked through our samples and seen that it’s a real SQL service, however, you probably want to figure out how to get the most basic pieces of our system configured for your environment. That’s what I’ll try to cover here.
Basic domain properties
When you install NuoDB one of the first things that happens is that a local management agent starts running. As I explained in my previous entry, that agent is configured by default from a local properties file. For most deployments of the software, there are a couple of these properties that you’ll want to configure.
In my previous examples I always showed the local agent running as a Connection Broker. That’s because the product ships with this property set:
# A flag specifying whether this agent should be run as a connection broker broker = true
We ship the product this way to make it easy to get running out of the box, but in a real deployment you typically want only a few agents running as connection brokers. As long as you have more than one broker you’re running in a redundant mode. If you set this property to false (or just comment it out) then your host will have an agent that’s monitoring and managing only what happens on the local host and reporting everything back to some broker in the domain. For more on how to connect your hosts see the discussion of the “peer” property in the previous getting started entry.
Another property you may want to change is the allowed port range. When an agentstarts a Transaction Engine or Storage Manager it’s starting a server process that needs to listen on some port. If you have firewall rules in place then you probably want to lock down what ports are allowed for use by the database processes. Here’s the property for that:
# A range of port numbers that nuodb instances should be confined to. This is # of the form start[,end] #portRange =
So, for instance, if you set portRange = 48010,48020 it will restrict the local database processes to using the 11 ports (inclusive) in that range. Of course, this also limits you to running 11 processes total on the host, so think carefully about how tightly you want to lock down your firewall versus how many databases you need to support.
Note that if you really want to lock down a host to only run a single TE or SM you can also set this property to a single value. For instance, setting portRange = 48010 will mean that you can only run a single process that will listen on port 48010.
One final property to note is the name of your domain:
# The name used to identify the domain that this agent is a part of domain = domain
This is really just a way for you to name your domain to make it easier to work with from our tools. If you change this string, re-start your broker and then re-connect in the web console you’ll see this name reflected in the admin interface. If you’re not trying to manage multiple domains then you’ll probably never need to worry about changing this property.
Domain administration accounts
As of the 1.1 release NuoDB uses a simple authorization model for managing a domain. You can create as many administrative accounts as you like, but they’re all essentially “root” users that have equal privileges.
By default, there’s always a user named “domain”. That’s the identity used by the agents that are connected together to support your domain. This user’s password is configured here:
# The default administrative password, and the secret used by agents to # setup and maintain the domain securely domainPassword = bird
All agents must be configured with the same password. Yes, we know it’s not ideal. Sorry. We’re working on a much more flexible and hardened model for our next release. In the meantime this property is why, out of the box, you can log into the web console with the username “domain” and the password “bird”.
What we suggest you do is a couple of things. First, change this password to something harder to guess. In fact, if you look at our Amazon Web Services examples (both the cloud formation and python provisioning example) we use a long random string as the password and never tell the user what that password is. That brings us to the second thing you should do.
The command-line manager tool lets you create additional domain administrator accounts. There’s an example in our documentation (skip step 1, since you already have a broker running). We suggest you create additional administrative accounts and use those to manage the system. Like it says in the documentation you might also create an account specifically for the web console and then update the webapp.properties settings to use that new account.
The accounts you’re creating here are for the domain only. These accounts don’t give you any access into the internals of a given database. No matter how many domain administration accounts you create you’ll still pick a DBA username and password when you first start a database, and from there you’ll use the usual SQL commands to create additional accounts or roles and to grant or revoke privileges.
Let’s say you’re on Amazon Web Services. Every instance you start has two addresses associated with it. One is the internal address (or private address) that’s meaningful only within the Amazon network. For example, if you see a 10.* IP address that’s something internal. The other one is an external address (or public address) that’s addressable from the public Internet. In the case of AWS there’s also a name associated with each address.
The thing is, the operating system running on your instance only knows about the internal address, because that’s what it was configured to use when talking with the rest of the network. The external address is part of the AWS infrastructure. This is also what you’d see if you were behind a NAT, or working in any similar protected network.
If you have a management or SQL client running outside of AWS and connecting into AWS you need your Connection Broker to advertise external addresses. The simplest way to tell NuoDB about an external address is with this property:
# An alternate address to use in identifying this host, which is not actually # advertised unless the advertiseAlt property is set. #altAddr =
So, for instance, on AWS you might set altAddr = ec2-54-224-104-158.compute-1.amazonaws.com for a host with internal address ip-10-245-81-49.ec2.internal. Now all of the processes started on this host will have both addresses associated with them. By default they are advertised using the internal address but they will also have the external version as their alternate address. I recommend you set this property on any AWS host that you want to work with from outside an AWS region.
In order to see one address versus the other from a management or SQL client point of view, you also need to set this:
# A flag specifying whether the alternate address should be advertised instead # of the locally observed network addresses. This is only meaningful for # brokers, because only brokers advertise addresses to clients and admins. #advertiseAlt = false
This flag is only needed on a broker. A broker advertises agents and database processes with a single address, and by default uses the address known to the OS. In this example, that’s the internal address.
If you set this flag to “true” then the broker will advertise the alternate address. In this case, that’s the external AWS address. This will let your external clients interact with your internal services. If all or your NuoDB interaction is private to a single region then you don’t need to set this up. In all other cases I strongly suggest that you use alternate addressing.
To make your life easier, if you use our cloud formation script on our marketplace image, or provision using the python script we bundle with the release, we’ll setup alternate addressing for you. So, you know, you’ll be all set out of the box.
Using what you’ve learned here, and the previous entries on getting started with domains and databases you should have everything you need to setup a real-world deployment. Hooray!
In the next few months we’ll be talking about some exciting new features we’re rolling into the next release. Those will include updates to the security and configuration model, an easier way to work with databases and better integration with services like AWS. For the meantime, we’d love for you to give a multi-host configuration a test-drive and tell us what you think!