Alpha1 Release Notes - Duckwater Demo

Duckwater Demo Page

The files on this page are covered by a variety of licenses: the OpenSolaris Binary License, the Common Development and Distribution License (CDDL). The specific license for each file is indicated in the rightmost column of the table below.

NOTICE PURSUANT TO SECTION 9 OF THE COMMON DEVELOPMENT AND DISTRIBUTION LICENSE (CDDL)

The OpenSolaris code released under the CDDL shall be governed by the laws of the State of California (excluding conflict-of-law provisions). Any litigation relating to this License shall be subject to the jurisdiction of the Federal Courts of the Northern District of California and the state courts of the State of California, with venue lying in Santa Clara County, California.

Downloadable Demo Files

The following are links to the demo tar images.

• Current x86 Demo - TAR format
• Current Sparc Demo - TAR format

Overview & Warnings...

This is a first release (alpha prototype) of the Duckwater project into the
wild. We decided to do a public release to show our progress, to let
people see where we're going and most importantly to get feedback and
ideas from community about how  you will use it, what more (or less)
features you would like to see etc.

Please note, that is live demo snapshot of our work in progress.
It is not just a mock up. These tools will configure (and administer) name
services configurations and the name service switch subsystem.  It is
possible to get into trouble.  At this time we do not recommend that this
demo be used on any production machine(s), because this demo has not gone
through formal regression testing.   You might be lucky, and we would like
to hear about it, but if not, then you may end up running sys-unconfig
or worse on the machine.  Please be forewarned.  We would certainly
appreciate to hearing about UI issues, bugs and problem areas in the demo
as well.

So far, we haven't been able to do much of the formal regression
testing. This is the reason we are not releasing BFU archives this time. It
is our priority, in the coming weeks, to get to a point where we can start
running standard regression tests on the project code.  When we are reasonably
confident that the software is shown to be stable, we plan to
deliver another demo release that includes BFU archives for people to
test as an integrated part of OpenSolaris.

And just in case you wanted to ask - yes, we are running the bits on our
machines today, and yes, it (mostly) works

Be sure to check the Known limitations section.

Requirements

The ON (OS/Networking) portion of your target machine must be running
build 67 or later of Solaris Nevada (SunOS 5.11).

Before you start using this demo

Prior to using the demo please backup your name services related configuration.
Below is the list of files the demo may/will touch one way or another.

Some, which are standard public interfaces:

    /etc/nsswitch.conf
    /etc/resolv.conf
    /etc/defaultdomain

A few files you may not know about:

    /var/ldap/ldap~_client~_file
    /var/ldap/ldap~_client~_cred
    /var/yp/binding/<your~_domain~_name>/ypservers

The prototype makes sure not to ever delete or rewrite anything without
first making a backup copy. The backup file names are generated using
mktemp(3C) call and the template is
<filename>duckwater~_backup~_XXXXX.

The new configuration is stored in the SMF repository and the data
stored in SMF has precedence - i.e. it is used as main source and
(if/as needed) legacy configuration files are generated.

Package and installation

Installation is as simple as getting the tar file for your architecture
(i386 or sparc) and untaring it anywhere in your system (we
suggest /var/tmp, but it's really up to you). dwdemo directory
will be created with following content (for more information about the
package content, please refer to appropriate tar file README file):

    ldapaddent*
    ldaplist*
    nsadm*
    nscfg*
    usr/

All the commands in the first level are a wrapper shell scripts -
these are the ones you need to execute.  The wrapper scripts set
the PATH and
LD~_LIBRARY~_PATH environment variables and then call the appropriate
binary from usr/bin or usr/sbin. The wrapper scripts are written
in such a way that your current directory has to be the dwdemo -
e.g. /var/tmp/dwdemo.

This has been done so that the production OpenSolaris libraries and binaries
are unmodified by this demo.

The first and most important thing after installation you should do is create
the initial name services profile by importing the actual
configuration of your system. This is done by nscfg import
my~_first~_ns~_prof command (you have to be root for this). Please read
more about this in Configuration tool - nscfg(1M) section.

The use of Solaris Auths, Roles Privileges by these tools is still under development.

Components of the release

Name services related LDAP tools

Yes, we know everybody is very excited to try our new name service
configuration tools, but we have some very cool new stuff in LDAP naming
area as well.

The release versions of the LDAP client utilities do not allow
the user to specify a LDAP server for ldapaddent(1M) and
ldaplist(1) directly. The production utilities can only be used
after the systems has been initialized as an LDAP client. And only then
is the administrator able to use ldapaddent(1M) and ldaplist(1) to easily
check the schema of the directory and populate the directory with user data.

This project enables the utilities to work in 'standalone' mode.
I. e. the user will be able to specify a directory server using command
line options of these utilities instead of initializing the LDAP client
on a production machine in advance.

If you create a LDAP NSBEC using nscfg(1M), you'll be able to do::

    $ ldaplist -B ldap~_bec~_name passwd
    ...

Or, if you know the IP address of the directory server and domain it is
serving, you can do::

    $ ldaplist -H 192.168.0.1:389 -M example.com

The same applies for ldapaddent.  This makes it easier for administrators
to populate the directory using existing (NIS) data prior to LDAP client
machine setup. 

Configuration tool - nscfg(1M)

This is the tool you use to create and manage name services subsystem
configurations and organize them into profiles. You can run the tool in
the interactive mode - much like svccfg(1M) - or issue one command
at a time directly from your shell - in that case verbose mode is
automatically enabled and autocommit is set to yes.

The idea is that you create a switch profile (NSSP) and number of
back-end configurations (NSBECs) and then link the NSBECs to the NSSP.
That way you create a integrated name service profile, which you can use
nsadm(1M) to switch to.

Such a name services profile can look (for example) like this::

    \+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\+              \+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\+
    \| NSSP: TEST1      \| \-\-\-\-\-\-\-\-\-\->  \| DNS NSBEC: dns1    \|
    \+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\+              \+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\+
    \|hosts: files dns  \|              \| domain: abc.xyz    \|
    \|passwd: files ldap\|              \| search: abc.xyz    \|
    \|                  \|              \| namserver: 1.2.3.4 \|
    \|...               \|              \+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\+
    \+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\+ \            
                          \-\-\-\-           
                              \       \+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\+
                               \-\-\-\->  \| LDAP NSBEC: ldap1  \|
                                      \+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\+
                                      \| ...                \|
                                      \+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\+

Autodiscover name services configuration

There are a few ways, how you can create name service profiles (or
NSSPs). One of the ways, most comfortable for many workstation / laptop
users is automatic discovery. Yes, that's right! Just run
nscfg(1M) and type in the following commands::

    nscfg>  discover -n at_work
    Discover timeout is defaulting to 5 sec.
    1 back-end(s) discovered
             nis at~_work
                    domainname = "nisdomain.example.com"
                    serverlist = "192.168.1.100"
             nsswitch at~_work
                    passwd = "files nis"
                    group = "files nis"
                    hosts = "nis [NOTFOUND=return] files"
                    ipnodes = "nis [NOTFOUND=return] files"
                    ...
                    PROF~_profile~_be~_yp = "at~_work"

What happened above was that nscfg(1M) (with help of DHCP) found information
about local NIS server (it's IP is 192.168.1.100 and it's serving
domain nisdomain.example.com), it created instance of NIS
configuration (NSBEC - see Glossary), filled it with the data and then
it created switch profile (NSSP), added 'nis' as a source type for
various databases (passwd, hosts, etc.) and then it associated (see
the PROF~_profile~_be~_yp property) the NIS configuration at_work to
switch profile at_work - it is to make sure that when profile
at_work gets enabled by nsadm(1M), that also the appropriate NIS
configuration gets activated too.

Import existing legacy configuration

Another way to create a profile is by importing the actual
configuration of the system from the legacy configuration files - like
the ones mentioned in the section Before you start using it which
talks about making backups - what, you haven't seen that one? Hmm.

    nscfg> verbose
    Verbose mode on.

import your existing configuration    

    nscfg> import my~_first~_ns~_prof
    Info: Importing legacy configuration files for [nsswitch].
    Info: Importing legacy configuration files for [dns].
    Info: Assigning DNS configuration to the profile.
    Info: Importing legacy configuration files for [nis].
    Warning: Legacy configuration files for [nis] not found.
    Info: Importing legacy configuration files for [ldap].
    Warning: Legacy configuration files for [ldap] not found.
    Info: Going to save data to repository.
    Info: Profile [my~_first~_ns~_prof] created.

Manual name service profile creation

Third option is to go the hard way and do it all manually - don't worry
it's not that bad, but it is a little work:

    nscfg> verbose
    Verbose mode on.
    nscfg> create nsswitch at~_home
    nscfg/nsswitch/at~_home> listprop
    [pre-filled properties will be shown]

set properties if you need to

    nscfg/nsswitch/at~_home> setprop ...

save

    nscfg/nsswitch/at~_home> commit
    nscfg/nsswitch/at~_home> unselect
    nscfg> create nis at~_home (What, you don't have NIS at home? ;-))
    nscfg/nis/at~_home> setprop domainname=example.com
    nscfg/nis/at~_home> setprop serverlist=192.168.1.100 (your NIS)
    nscfg/nis/at~_home> commit
    nscfg/nis/at~_home> unselect

associate nsswitch profile at_home with NIS configuration at_home

    nscfg> associate nsswitch at~_home nis at~_home
    nscfg/nsswitch/at~_home> commit

    [you're done]

Please note, then when creating the configurations manually (using
create command), the nscfg(1M) will give create a template for
you with all the possible properties. Some of them will have default
values, some will be empty. It is your responsibility (in the alpha
demo) to make sure the configuration is valid and complete.

Administration tool - nsadm(1M)

This is the tool you use to get a view of all the name service
profiles defined in the system, their current state.
More importantly, this tools allows you to switch between several
different profiles.

List profiles on the system

To get a view of what profiles are defined in the system and which one
(if any) of them is active (online), issue following command:

    $ nsadm list

    (online) Profile 'test-1' (NIS:'test-1')
             Profile 'test-2' (NIS:'test-1', DNS:'test2-dns')
             Profile 'files'  ()
             Profile 'auto'   (NIS:'auto')

nsadm(1M) would also warn you if there's any problem with the back-end
components. For name services data sources (a.k.a. back-ends) (e.g.
ldap) there's need to have a service running (e.g.
svc:/network/ldap/client:default) and nsadm(1M) checks whether the
service is really in desired state.

Switch to different profile

To enable a different profile (or as we say to switch into a different
profile), do simply this::

    $ nsadm enable  test-2
    Going to enable NSSP [test-2].
    Going to enable dns/client.
    Going to enable/refresh nis/client.
    Going to disable ldap/client.
    Do you want to proceed? [y/N] y
    Going to enable dns/client.
    Going to enable/refresh nis/client.
    Going to disable ldap/client.
    NSSP switched successfuly.

Known limitations/bugs

    - There is currently no support for NIS+.
    - The property names in the profiles and configurations are going to change.
    - So does the way we store the configuration data in SMF and how we handle switching between profiles.
    - IPv6 is relatively untested to date.
    - Verification of configurations and profiles is not implemented at the moment. If you create a incorrect/incomplete configuration, you will not be warned of configuration problems by the tools.
    - Properties in profiles and configurations are currently displayeed reverse sorted order.
    - When doing discovery, we get only IP address of a NIS serve from DHCP, so entries in /etc/inet/hosts are added incorrectly
    - {{code}}ldapclient(1M){{/code}} has not been ported to Duckwater yet. Please use {{code}}nscfg(1M){{/code}} and {{code}}nsadm(1M){{/code}} exclusively for now. Later in the project, we will deliver a modified ldapclient that is integrated into the Duckwater infrastructure.
    - {{code}}ypinit(1M){{/code}} - same as with {{code}}ldapclient(1M){{/code}}  The demo includes it's own (private/modified) version of ypinit
    - Only static DNS configuration is supported. Of course, if you call {{code}}discover{{/code}} command from {{code}}nscfg(1M){{/code}}, it will get the DNS information from DHCP.
    - Manual page coverage is poor. All commands ({{code}}ldaplist{{/code}}, {{code}}ldapaddent{{/code}}, {{code}}nscfg{{/code}} and {{code}}nsadm{{/code}}) have pretty decent help and they all of course should be intuitive to use ... the latter two anyway.

Glossary

NSSP, nsswitch, profile 

Name Service Switch Profile. We sometimes refer to it as 'switch
profile' or just 'profile'. nscfg(1M) knows it by name 'nsswitch'. And
yes, we're working on consolidate the terminology

NSBEC

Name Service Back-end Configuration. Sometimes refered to as 'backend
configuration' or simply 'configuration'.