NDSLogin v MT-3.12
==================
  (Jan 12, 1997)


DISCLAIMER
----------
     THIS PRODUCT IS SUPPLIED "AS IS". THE AUTHOR DISCLAIMS ALL WARRANTIES,
     EXPRESSED OR  IMPLIED,  INCLUDING, WITHOUT  LIMITATION, THE WARRANTIES
     OF  MERCHANTABILITY AND OF FITNESS FOR ANY PURPOSE. THE AUTHOR ASSUMES
     NO  LIABILITY FOR  DAMAGES, DIRECT OR  CONSEQUENTIAL, WHICH MAY RESULT
     FROM THE USE OF THIS PRODUCT.


Introduction
------------
NDSLogin is a DOS command-line utility that allows a user to log into a
NetWare 4 NDS tree using simply a username, without having to know the
context in which the username is located.

This feature is useful in installations where users do not wish to learn
about the longer naming convention, or to simplify travelling users. In
general, a name context is specified in the NET.CFG on each workstation.
This helps the owner of the workstation to log in. However, if another user
from a different department (context) needs to use this workstation to
log into the network, it is a little more involved. It is the goal of
NDSLogin to simplify such situations.

NDSLogin is simply a front-end utility to the standard NetWare LOGIN.
NDSLogin takes the same arguments as LOGIN, but tries to parse out the
username portion. Using the name, NDSLogin will search the NDS tree to
locate user objects with this (common) name. If there are duplicates, the
first 10 will be displayed and the user can choose from the displayed list.

Once the user object is located, and its context determined, NDSLogin passes
control to NetWare LOGIN. Therefore, all login script commands will be
processed.

Version 1.13 added the ability for you to "hide" LOGIN.EXE in a secret
directory under LOGIN and to ignore the /NS parameter. This gives you some
added security as the user will not be able to (easily) bypass the login
scripts you have set up for your network.

Version 3.00 gives you the ability of holding the user in a login-loop so
that the username need not be entered again should the login failed.


Notes
-----
 1. NDSLogin should be installed into SYS:LOGIN and SYS:PUBLIC, where
    LOGIN.EXE is located or is on a search path. It also makes it easier
    for the utility to locate the needed Unicode files.

 2. Only the first 10 match in names will be displayed. It is unlikely
    that you will have more than 10 users with the same user object
    names within the tree.

 3. NDSLogin has only been tested with NetWare 4.1. It is not expected to
    be dependent on the version of NetWare, however, only time will tell.

 4. If you load memory resident applications (TSRs) from the login script,
    extra configuration steps are required. This is to avoid DOS memory
    fragmentation.

 5. NDSLogin has not been tested with other LOGIN interfaces, such as Intel's
    LOGIN.COM. As a matter of fact, NDSLogin calls LOGIN.EXE explicitly,
    therefore, it is not compatible with Intel's LOGIN.COM.
 
 6. If you use the PREFERRED SERVER option in your NET.CFG (or PS= with your
    VLM), the DEMO version will not be able to find a tree. You need to
    first establish a DS connection first; the PS option sets up a bindery
    connection. You can establish a DS connection in two ways: a) login to
    the server using LOGIN.EXE normally and logout; or b) use the PREFERRED
    TREE option (or PT= with your VLM).

 7. It seems like there may be a bug with the NetWare Client API's search
    function. It is easier to explain this with an example. Consider a sample
    NDS tree:
               [Root]
                 |
             O=DreamLAN
                 |
              ---+---
             |       |
                  OU=NW4SG
                     |
                  ---+---
                 |       |
              CN=Test  OU=NW4SG
                         |
                       CN=Test

    If you set the BaseContext to NW4SG.DreamLAN and give Test as the username
    to search for. NDSLogin will come back with 2 hits (correctly) but will
    show that both Test objects are in the first NW4SG container. However, if
    you set the BaseContext to DreamLAN, then the context of the found Test
    objects are reported correctly (Test.NW4SG and Test.NW4SG.NW4SG). If there
    is no two subsequent levels with the same name, the problem does not
    occur. Therefore, if the second NW4SG is changed the NW4SG-2, then the Test
    user objects are found with the correct context information. This problem
    _may_ have been addressed with v1.12 of NDSLogin.

 8. If you specified the /B option as one of the options, that means you wish
    to log in using Bindery Services. In this situation, NDSLogin will _not_
    search the NDS tree for the user object name. Rather, it will simply pass
    the user object name, plus other "slash" parameters to LOGIN.EXE. It will
    be up to the server to determine if the specified user object exists
    within the bindery context of the server.

 9. Use of wildcard in the username is not supported.

10. There is one report from a Token Ring site that NDSLogin will lock up the
    the workstation _if_ the workstation was logged into the network. However,
    we have been unable to reproduce this issue on other Token Ring or
    Ethernet networks. It may have something to do with this site's specific
    workstation configuration. This only happens when the colour support in
    NDSLogin is turned on. As a result, the colour mode (controlled by
    ColorMode in the CFG file) is OFF (False) by default.

11. In a very large tree with multiple partitions, where some partitions are
    not local, becareful where you start the BaseContext search from in the
    configuration file. By default, the search starts at [Root]. If you do not
    have a copy of [Root] locally or there are remote partitions across slow
    WAN links, NDSLogin may appear to hang the workstation as it tries to
    tree-walk. In such situations, it is best to limit the scope of the search
    to local partitions or use IncludeContext in the CFG file to specify which
    containers to search the username.

12. NDSLogin will only accept parameters for LOGIN.EXE at the command-line
    level. You can not specify any parameters if you are prompted to enter
    the username.

13. If you specify any IncludeContext containers, the BaseContext parameter
    is ignored.

14. You should give it some thought when using IncludeContext. You should not
    specify an IncludeContext that is a subordinate of another. For example,
    ".NW3.NW4.TopLevel" and ".NW4.TopLevel". If you do this, you may get
    double (or more) hits on the same username.

15. The /? parameter is not passed to Novell's LOGIN.EXE. It is intercepted
    and is used by NDSLogin.

16. Make sure the directory path into which you install NDSLOGIN.EXE does not
    exceed 65 characters in length. (It should not be a problem in general,
    but does not hurt to mention this limitation here.)

17. NDSLogin does not currently handle a multi-tree environment. It will search
    for the user object in the tree the workstation is attached to. Therefore,
    if you have multiple trees, make sure you use the PREFERRED TREE option in
    your NET.CFG or /PT= option when loading VLM.

18. The use of ExcludeContext is "local" to the container you specified. For
    example, if you specified ExcludeContext = ".NW4.TopLevel", user objects
    in .NW3.NW4.TopLevel will be found, but not user objects in .NW4.TopLevel.
    Therefore, if you need to exclude both .NW4.TopLevel and .NW3.NW4.TopLevel,
    you need to specify two ExcludeContext entries.

19. It seems the color routine used in the NDS ToolKit software is
    incompatible with certain video cards -- the screen will appear to be
    blank after the banner is displayed. If you do a CLS the color is
    restored. In such cases, turn OFF the color setting in the CFG file.



Installing NDSLogin
-------------------
No special installation steps or program need to be used. Simply copy
NDSLOGIN.EXE and NDSLOGIN.CFG to SYS:LOGIN and SYS:PUBLIC of your servers.
You must have the unicode files for the country code and code page that
your workstation use available in the the respective NLS directories,
for example, SYS:LOGIN\NLS.

Without a valid license (defined in the CFG file), this copy of NDSLOGIN.EXE
runs in the demo mode. In the demo mode, the contents of NDSLOGIN.CFG
(if present) is ignored.

If your workstation's AUTOEXEC.BAT calls LOGIN automatically, one way you can
ease the transition to NDSLogin is to rename NDSLOGIN.EXE to LOGIN.COM and
place that in the SYS:LOGIN and SYS:PUBLIC directory. If you do this, however,
the CFG file will have to be named LOGIN.CFG. Basically, the CFG file will
have to be named after whatever you renamed NDSLOGIN.EXE to be. If you are
using Intel's LANDesk Manager, for example, there is already a LOGIN.COM. In
such situation, you will have no choice but to update the workstations'
AUTOEXEC.BAT files.


Running NDSLogin
----------------
You use NDSLogin just like you would with LOGIN:

     NDSLOGIN username [other LOGIN.EXE parameters] [-T] [-Q]

If you specify a context with the username, NDSLogin will not search the
tree, but will simply pass the information on to LOGIN.

A special -T (TestMode) command-line switch allows you to run a registered
copy of NDSLogin in the Demo mode. This is useful if you wish to test the
program on a tree that is different from the one the copy is registered for.
In the Demo mode, the .CFG file is not read.

If you are using NDSLogin as part of a batch file and would like to suppress
the display of the copyright information, use the -Q (Quiet) option.

If your login script loads any TSRs, you need to create a batch file,
similar to the following, to use NDSLogin:

     @Echo off
     NDSLOGIN %1
     CALL C:\LOGIN_DS.BAT
     DEL C:\LOGIN_DS.BAT

and you will need to create a NDSLOGIN.CFG file and specify HasTSR to TRUE
(see below). The reason for doing this is to prevent DOS memory fragmentation
of loading a TSR while NDSLOGIN spawns a process to run LOGIN.EXE.

You can use the same technique if NDSLOGIN/LOGIN reports insufficient
memory to execute some external program. During testing, we have not come
across any insufficient memory problem.

Note:
-----
The NDSLOGIN.CFG file must be in the same directory as where you have
NDSLOGIN.EXE. Therefore, if you installed the EXE into both SYS:PUBLIC
and SYS:LOGIN, a copy of the CFG must be in each directory.


Configuring NDSLogin
--------------------
You can control the following functions of NDSLogin using a NDSLOGIN.CFG
(or whatever.CFG if you renamed NDSLOGIN.EXE to whatever) file:

     1. Banner1        = text          (no default)
     2. Banner2        = text          (no default)
     3. Banner3        = text          (no default)
     4. BaseContext    = contextname   (default is [Root])
     5. ColorMode      = TRUE or FALSE (default is FALSE)
     6. ExcludeContext = contextname   (no default)
     7. HasTSR         = TRUE or FALSE (default is FALSE)
     8. IncludeContext = contextname   (no default)
     9. LocalMode      = TRUE or FALSE (default is FALSE)
    10. LoginLoop      = 'number'      (default 1; max 5)
    11. NoLogo         = TRUE or FALSE (default is FALSE)
    12. Quiet                          (a toggle)
    13. SecureLogin    = TRUE or FALSE (default is FALSE)
    14. SetContext     = TRUE or FALSE (default is FALSE)

Banner1 through Banner3 allows you to configure a simple 3-line banner. Use
Banner1 for the first line, Banner2 for the second, and Banner3 for the
third line. Each line is limited to 80 characters, and will be automatically
centered.

The BaseContext setting allows you to specify from which container NDSLogin
will start searching from. This is useful if you have a large tree or if
you do not have local replicas of the partitions. This will speed up the
search time considerably. The drawback is that you have limited the scope of
the search. The context name is relative to [Root], therefore, you should not
place a period in the beginning.

The ColorMode flag indicates if NDSLogin should use colour on the display or
not. The default is black/white.

The ExcludeContext option allows you to specify which containers will the
userids not be included as "hits" in the search. These containers are still
searched for the object, but any hits will be discarded. Opposite in function
to the IncludeContext option (see below). There may be times that rather than
including 7 containers, you may be able to exclude 2 containers instead. Up
to 10 ExcludeContext entries may be specified.

The HasTSR flag indicates to NDSLogin if the external batch file
(C:\NDSLOGIN.BAT) is to be created or not. Using this option will cause the
workstation's name context to be switched to where the user object name is
located. But the batch file created by NDSLogin (i.e. C:\LOGIN_DS.BAT) will
restore the workstation's context back to where it was before with a CX
command.

The IncludeContext option allows you to select the starting container from
which NDSLogin will search for usernames. Up to 10 may be used. The BaseContext
option is ignored if IncludeContext is used.

The LocalMode option will limit the search to terminate at the first hit.
This is useful if you have specified multiple contexts to search as this will
return the result faster. This is especially useful if some of your contexts
are across WANs and you do not have a local replica.

The LoginLoop option allows the login program to "loop" a number of times
in case the login was not successful. This is useful in "locking" the user
in the login mode without having to specify the login name again. However,
this option is only useful if you are _not_ using the HasTSR option. If
you are using the HasTSR option, you need to modify the batch file that calls
LOGIN_DS.BAT and test for ErrorLevel - a non-successful login will return
a non-zero value.

By setting the NoLogo option to TRUE, the red "Novell NetWare" banner from
the LOGIN.EXE is not displayed. This option is set to TRUE if you specified
the Bannerx (see above) flags. Or you can set this to TRUE without using any
of the Bannerx flags.

The Quiet option (no parameters) will turn off the copyright information
being displayed during the initial screen.

By setting SecureLogin to TRUE, NDSLogin will disallow the use of /NS and
execute LOGIN.EXE from a directory called NDSL under your current working
directory. You can flag NDSL hidden to prevent the user from finding where
LOGIN.EXE is placed. When you place LOGIN.EXE in the NDSL directory, you
also need to place a copy of LOGIN.MSG there as well. If you use this option,
you should make sure if you are using the batch file to launch NDSLogin
(because of TSRs) the batch file deletes the LOGIN_DS.BAT file as it contains
the location of the hidden directory. Some drawbacks of this option:

     1. a skilled user can find the hidden directory without
        "too much" effort;

     2. a legit use of LOGIN.EXE with /NS option from the
        SYS:LOGIN directory would not be possible;

     3. a user logged into the network can possibly execute
        LOGIN.EXE from SYS:PUBLIC and specify the /NS parameter.

Therefore, this option is not fool-proof, but it offers additional security.

The SetContext option changes the workstation's context to where the user
object id is located.


None of the commands are case sensitive.


Note: NDSLogin does not check the validity of the context name
----  you entered.


Registration
------------
Two variations of NDSLogin are available. The version included here is a
Freeware version. It does not read the NDSLOGIN.CFG file. That means the
search will ALWAYS start from the [Root]; it does not support the loading
of TSRs in the login script; and the screen will only be in black/white.
This Freeware version will not handle duplicate names; the first hit will
be returned. (See what else it will not do by referring to the "Configuring
NDSLogin" section above.)

You are granted an unlimited usage to the Freeware version at no cost.
However, you are not allowed to sell or package this utility as part of
another software package or service contract. Bottom line: you can not make
money using this Freeware version. All standard Freeware limitation applies.

Should you find the need, a registered version is available for $99US.
This will be a NETWORK license, limited to ONE NDS TREE.

Special site agreements for multiple trees and service providers are available.
Although the license does not grant you the right to resell the program (i.e.
for a profit; but you can charge the customer a service charge for your time).
If you are a service provider, you can register copies on behave of your
customers (by providing your customer's mailing information -- this is used
only for tracking purposes). At the same time, we ask you to send us a
separate email indicating that you are registering on behave of your customer
and inciate in this email if further software upgrade (free or for a charge)
be send to you or the customer directly, and an email address for that purpose.

You will be contacted for your NDS tree name information after your
regsiteration is received. However, to avoid delays, you can send email
with the NDS tree name information to the author.

The registeration can be performed via CompuServe (!GO SWREG) or via FAX. If
you can not register via CompuServe, you can FAX a Purchase Order to
(905) 886-2534. Please make sure you either include your tree name information
on the FAX or send a follow up email. Canadian orders is $135 CDN plus GST.
All other countries, please remit in US funds.


Other Information
-----------------
NDSLogin is written in C using Microsoft C optimizing compiler and Novell's
Client SDK v1.0e. Some string manipulating routines are from the CXL library
and some color routines are from TCIO library.


Revision History
----------------
Sep 25, 1995. Version MT-1.00, first released code.

Sep 30, 1995. Version MT-1.10, added support to deal with workstations that
                               use the PREFERRED SERVER option in NET.CFG or
                               /PS= when loading the VLM.

Oct 03, 1995. Version MT-1.11, added support for /B (bindery mode) login.

Oct 25, 1995. Version MT-1.12, added support to include containers.

Nov 17, 1995. Version MT-1.13, added support to surpress /NS to LOGIN.EXE.

Jan 08, 1996. Version MT-1.14, minor context naming bug fix. Returns the
                               ERRORLEVEL as set by LOGIN.EXE.

Jan 28, 1996. Version MT-1.15, removed requirement of NDSTreeName option from
                               .CFG file. Enhanced treename checking.

Jan 30, 1996. Version MT-1.16, better context information support for the
                               DEMO version.

Jan 31, 1996. Version MT-1.99, added support for a Test mode (-T command line
                               switch). Not Released.

Feb 01, 1996. Version MT-2.00, enhanced error checking in CFG file (this
                               version was not released). Added support to
                               suppress LOGIN.EXE's banner and option to
                               supply a simple 3-line banner. Not Released.

Feb 02, 1996. Version MT-2.20, added support to exclude container and option
                               to set workstation context to where the userid
                               is found.

Feb 16, 1996. Version MT-2.21, added a "quiet" mode command-line option to
                               suppress the copyright message. Handy when
                               using NDSLogin from a batch file.]

Mar 05, 1996. Version MT-2.25, relaxed the checking on NDS treename and
                               primary connection ID info. This was causing
                               an error report (on running NDSLogin again)
                               after the user is attached to server that does
                               not have a replica of the user information, and
                               must tree-walk.

Mar 10, 1996. Version MT-2.26, fixed a name context issue when duplicated ids
                               are found and IncludeContext is used.

Mar 13, 1996. Version MT-2.27, fixed a name context issue when there is no
                               duplicated ids when IncludeContext is used.

Apr 27, 1996. Version MT-3.00, added two new keywords: QUIET and LOGINLOOP.

May 06, 1996. Version MT-3.10, changed to use licensing information from the
                               CFG file.

May 13, 1996. Version MT-3.11, improved error messages and added one testing
                               mode.

Jan 12, 1997. Version MT-3.12, fixed a name context issue when the user object
                               is in the current context.

