 |
|
 |
The Sybase Interfaces File
This is not intended to be a definitive 'white paper' on the interfaces file, but a review of basic information gathered from eight or so years working with Sybase, it has a very Solaris bias but that is where my experience lies. Some information is directly referenced from the Sybase website, this has been highlighted in the text, other information comes from my own experience. As usual this information is offered 'as is' and no liability will be accepted. Any constructive comments will be appreciated you can e-mail me at johnx@outlands.demon.co.uk.
This information is offered to complement two applets I have written for converting IP/Port numbers to TLI strings and vice versa, see ip2tli and tli2ip. Again these are offered as is, if your company wants these programs contact me at the above address.
The interfaces file provides UNIX clients and servers connectivity information about a Sybase server.
It provides two main functions, from the server point of view it provides the means to start network listeners upon server boot, if it can't resolve the information in the interfaces file the server will fail to start. As far as the client is concerned the file provides client programs, isql, bcp etc. with connection information to the server.
The file comes in two formats, a sockets based form and a TLI style. The non-TLI style is by far the easiest to read and has the following format:
## SERVERNAME on HOSTNAME
## Services:
## query tcp (Port Nos)
## master tcp (Port Nos)
SERVERNAME 5 1
query tcp ether HOSTNAME PORT
master tcp ether HOSTNAME PORT
Comments begin with ## or # these are added by programs such as sybinit that you can use to write out interfaces files. The important part is the last three lines of the entry. The first line states that the following information refers to the server called SERVERNAME. The two digits after the name are the 'retry count' - how many attempts the client tries to connect before generating an error message, and the 'retry delay' how long it waits before it tries to connect again. These values are optional, in the above example the client will try five times every second before generating an error message.
The two digits after the server name refer to the retry count and interval when connecting to the server. It is important to realize that the next line begins with a TAB, "\t" or whatever you call it. The query port which is where clients connect to find the server, tcp indicates that the TCP/IP network protocol is used. ether indicates the network type, the hostname could be a hostname, a fully qualified DNS name or an IP address, and the final entry is the port number to connect on. The second line is the master port which is where the server listens for connections. In older versions of Sybase(pre 10.x) you may also see a console entry which was used for dump and load operations that spanned tapes.
TLI format file looks like this
SERVERNAME
master tli tcp /dev/tcp \x000213880a8d6b360000000000000000
query tli tcp /dev/tcp \x000213880a8d6b360000000000000000
In the later versions of tools such as dsedit comments are no longer written
out, hence the slightly more spartan look. Again the first line identifies
the SERVERNAME, master and query are the same as above, tli indicates that
the machine has a TLI based programming interface. tcp is the same as above,
'/dev/tcp' is the device file which acts as an interface between the user
program and the networking software, the network "end point."
The hexadecimal string can be broken down as follows.
| Indicates that this is a "tli address" family. This is always the start of the start of a TLI address. TCP/IP is family 2, depending on network vendor and byte order of the machine, the most common is 0002, or 0200 depending whether the machine is 'big endian' or 'little endian'. Check your current interfaces file. | This is the hexadecimal equivalent of the port number | This is the first part of the IP address. | This is the second part of the IP address. | This is the third part of the IP address. | This is the fourth part of the IP address. | This is a 'padding' value, and is platform dependant, on Solaris it is 16 zeros. It is mandatory |
And now for a cheap plug - try ip2tli and tli2ip to convert between hex and IP/Port formats.
| Operating System | TLI/Non-TLI | Network Protocol | Example service line format |
| SunOS | Non-TLI | Ethernet | query tcp sun-ether HOSTNAME PORT |
| Solaris | TLI | Ethernet | query tli tcp /dev/tcp [HEX STRING] |
| AIX(IBM RS6000) | Non-TLI | Ethernet | query tcp ether HOSTNAME PORT |
| Linux | Non-TLI | Ethernet |
If you have any information on other operating systems please email me.
By default the interfaces file is located in the $SYBASE directory, if you check the RUN_SERVER file in $SYBASE/install, you will note that the -i arguement is used to specify the location for the dataserver to look, upon startup. You could specify another location with this option, please note that this refers to a directory in which to find a file called 'interfaces'. You can't use this arguement to specify another filename to use.
Clients, and by this I generally mean utilities like 'isql', 'bcp' or 'defncopy' (or even applications built on Sybase libraries) look in the $SYBASE directory. This can be over-ridden by using the -I option which point to an absolute pathname of a file.
Most grown-ups use a text editor of their choice, vi or emacs if you have developer
tendencies, this has advantages and disadvantages. It's quick, service lines can
be cut and yanked around the file, new entries can be quickly added, other files
can be read in. The downside is that there is no error checking that is provided
by some of the tools Sybase have shipped in the past for manipulating the interfaces
file. One thing I've found in older versions of connection utilities is that a
malformed entry will prevent you from connecting and may make the file unusable
for connection to some of the servers. So remember to take a back-up of the file
before you begin. There are two things worth checking if you've just edited the
file manually and you mysteriously loose connectivity to a server.
Sybase ships sybinit with versions 10.0.x to 11.0.x of its software, it is
located in the install directory relative to $SYBASE. A sample session looks like
this. As you can see it's quite long winded but
it works OK, it would be laborious to use this utility to create a 'master'
interfaces file.
In fact some people like sybinit so much they've written a freeware
version available at
Rob Verschoor's site. It is useful for building servers where you can't
run X and don't fancy editing resource files.
From 11.5 onwards Sybase offered dsedit to create and edit interfaces
files, it is located in the $SYBASE/bin directory. You will need to set your
DISPLAY variable correctly to get it to work, it is a full GUI driven program.
A sample session to add a server looks like this.
You can also access dsedit via the sybsetup utility.
Also provided with 11.5 onwards is dscp this is the obscure end of
interface file editing, it is a command line tool. A sample session to add a
server looks like this.
Troubleshooting connectivity problems
Sorting out connectivity problems can be problematical and time consuming, but
keeping a few basic principles in mind will help considerably. When you get a call
about a client not being able to connect to a host, you need to ask a few questions
Armed with the above information you are ready to look at the problem. The simplest
way to start is by 'cutting the problem in half'. Log onto the database server
and use ps to ascertain if the dataserver is running. Then try connecting
with isql, when you do this be aware that doing this utilizes some shell
variables $PATH, $SYBASE, $DSQUERY. What are these set to? If you can connect
locally on the box, make a note of these variables and the interfaces file details.
It's also probably worth checking the error log while your here to look for any
related error messages.
You have now ascertained that the server is up and accepting connections. If the
client is trying to connect from a UNIX box, say an application server, log onto
that box and ensure you can ping the hostname or at least the IP address.
If you can do that you have established that there is a network connection to the
dataserver. If you can't and you don't have root access it's time to call
the UNIX sa or Networks helpdesk. If you do have root access you should know what to
do next, this depends on your network topology and what messages you get back eg
No route to host etc.
After you are happy with the network try the isql again from the client
bearing in mind what $PATH, $SYBASE and $DSQUERY you are using. Have a look at
the interfaces file you are accessing, are the service lines identical as on
the server. So far so good? Now check the environment for the problem user.
What values of $PATH, $SYBASE and $DSQUERY are they using. Can you log in as them
and perform an isql. Which interfaces file are they using? If all is OK
you should start looking at the application - how is it getting these values.
If the client is a PC, check what means it is using to lookup server information.
Local interfaces, directory services or DCE, try the sybping that comes
with Open Client for NT or ping that comes with the OS, then repeat with isql
at the command prompt.
Configuring the 'localhost' interface
One of the features of TCP/IP is that every UNIX host has at least two
interfaces. You can view them with the netstat -i command
In the following examples I am using a sockets based interfaces file format
for readability, but the principles apply to TLI format files as well. Also
remember that these are server files, the localhost address on a client is
local to that machine only.
Configuring multiple listeners per interface
If you want to seperate groups of clients out onto seperate listeners or get a
single client off to an interfaces for troubleshooting/tuning purposes, the
following approach may be useful. Set up an alias in the /etc/hosts, NIS or DNS
or whatever your site uses.
Configuring a virtual interface
This is kind of a halfway house to the next technique, I haven't tried it myself
and I think there may be issues with plumbing and un-plumbing virtual interfaces
on Solaris, check with your UNIX sa/Network engineer.
Use ifconfig to configure a virtual interfaces, say 1e0:1, assign a hostname to
it in the hosts file and then set up an interfaces similar to the localhost
entry. There probably isn't much advantage to this other than monitoring
network activity, as both interfaces actually reside on the same physical
interface.
Configuring multiple interfaces
The setup of multiple physical interfaces is largely a matter of network
design, your site may have a disaster recovery network, or more commonly
a seperate backup-network that may be used for administration or other
batch jobs. All of this is relatively site dependant, however setting up
the host is relatively straight forward.
Each interface must have a unique hostname and IP address, these must
be registered in the hosts file or NIS/DNS, and the interface must be
up ie. can you ping the hostname. Set your interface file up like this
for the guiness host with a second interfaces called beamish.
If clients can access both beamish and guiness it is the order in which
the service lines appear in the file that matters. You could use guiness
as the primary network and beamish as the backup network should connection
fail. Alternatively you could distribute two versions of the interfaces
file to your clients.
guiness$ netstat -i
Name Mtu Net/Dest Address Ipkts Ierrs Opkts Oerrs Collis Queue
lo0 8232 loopback localhost 8824 0 8824 0 0 0
le0 1500 guiness guiness 38730318 5 3359447 13 2544 0
This was run on the host called guiness, you can see that the second row refers
to the 'le0' interface which is where all the network traffic arrives/departs.
The 'lo0' interface is a local interface that can always be accessed from only
that host, look in the '/etc/hosts' file and you will see that it always has
the same IP address - 127.0.0.1. Is this any use from the sybase point of view?
Well possibly, if you remember that an interfaces file has one service line for
a port and hostname, we could do something like this in our interfaces file.
GUINESS_PRD
query tcp sun-ether guiness 5000
master tcp sun-ether guiness 5000
query tcp sun-ether localhost 5000
master tcp sun-ether localhost 5000
When the server starts up with the above interfaces file, four network listeners
are started, two masters and two queries. Anyone using this interfaces file would
go through the guiness interfaces. However if say the sybase administration
account had another interfaces file called .interfaces in the sybase $HOME
directory and it looked like this
GUINESS_PRD
query tcp sun-ether localhost 5000
master tcp sun-ether localhost 5000
I could use the -I arguement to isql as follows
guiness$ isql -Usa -I ~/.interfaces
This would allow the sybase user to seperate his activity onto a different listener
possibly useful when running intense network i/o. Another plus to this approach is
that if the server had it's IP Address/hostname changed and was rebooted the
dataserver would at least boot, as it tries to start listeners in sequential order
it would fail on the guiness interfaces and then try and succeed on the localhost
interface. Although it would only be accessible locally, you could get in on the
console or physically go to the box and shut the server down cleanly.
If you want to set up a server and deny access to anyone else configure it with
the 'localhost' hostname. As you must be on the local box to access it, it won't
be available on the network. You can also have a localhost interfaces file that
you can use to reboot a server on for maintainance purposes. Is there any
performance improvements by using localhost, probably not as using 'guiness'
locally gets resolved to a local connection, whether this is done at the
server level or the TCP/IP level I'm not sure, any body knows the answer to this
one - please let me know.
10.10.10.10 guiness guiness_test
Set up an interfaces file like this on the server and reboot to get the new
listeners started.
GUINESS_PRD
query tcp sun-ether guiness 5000
master tcp sun-ether guiness 5000
query tcp sun-ether guiness_test 5001
master tcp sun-ether guiness_test 5001
You will note that each line in the hosts file represents an interfaces so the
port number in the interfaces file must be different. Set the client(s) up with
an interfaces file as below(also ensuring they can access the guiness_test alias)
GUINESS_PRD
query tcp sun-ether guiness_test 5001
You now have all traffic for the client(s) through a seperate port number and
listener.
GUINESS_PRD
query tcp sun-ether guiness 5000
master tcp sun-ether guiness 5000
query tcp sun-ether beamish 5000
master tcp sun-ether beamish 5000
Note that the port numbers can be the same as there are two instances of
the TCP stack. On a server reboot a network listener will start on the
guiness and beamish address. That is the server side of the configuration,
handling the clients really depends on if you have a common universal
interfaces file, how you distribute the interfaces file etc., some of
these issues will be discussed in the next section.
GUINESS_PRD
query tcp sun-ether guiness 5000
query tcp sun-ether beamish 5000
GUINESS_PRD
query tcp sun-ether beamish 5000
query tcp sun-ether guiness 5000
You could distribute version 1 to your London clients and version 2 to your
European clients thus segregating network traffic. Note each would provide
backup connectivity in the event of a network failure.
If you just wanted to distribute one interfaces file to all clients you would name the servers seperately so you could combine the above two files into one
GUINESS_PRD_LE0
query tcp sun-ether guiness 5000
query tcp sun-ether beamish 5000
GUINESS_PRD_LE1
query tcp sun-ether beamish 5000
query tcp sun-ether guiness 5000
Again London clients would use the GUINESS_PRD_LE0 name to access the server,
whilst European clients would use GUINESS_PRD_LE1. Again it swings and
roundabouts to which approach you use, it will depend on your site
architecture which is more appropriate.
Strategies for interfaces file deployment
There are several approaches you can use for interfaces file distribution and as mentioned above much of it is dependant on you site architecture. Personnally I prefer to keep the server interfaces file specific to the server, as the interfaces file can act as a line of security it makes it easier to understand what server to server connections are possible if interface files are unique to the server. In the server interfaces file you would have entries for the dataserver itself, the backup server, any replication servers or open servers that the dataserver needs to connect to.
If the server also acts as a client you could install the open client software in a different directory and point to it with a seperate $SYBASE to keep the interfaces files for clients and servers segregated. Alternatively if you have several fileservers you could have an instance of openclient on each and distribute interfaces files to each one, or maintain seperate ones if desired.
The means of distribution is generally limited by the OS and capabilities of any distribution software you use, but could include the following.
The most common problem occurs when a host is given a new hostname or IP Address, upon rebooting the box the server will fail to start up, inspecting the Sybase error log should show something like this
00:99/05/14 13:35:02.79 kernel ninit:0: listener type: master 00:99/05/14 13:35:02.79 kernel ninit:0: listener endpoint: /dev/tcp 00:99/05/14 13:35:02.79 kernel ninit:0: listener raw address: \x00024e22c2a984150000000000000000 00:99/05/14 13:35:02.79 kernel ninit:0: transport provider: T_COTS_ORD 00:99/05/14 13:35:02.79 kernel ninit: t_bind, Cannot assign requested address 00:99/05/14 13:35:02.79 kernel ninitconn_free: t_close, fd = 5, Illegal file descriptor 00:99/05/14 13:35:02.79 kernel ninit: All master network listeners have failed. Shutting down. 00:99/05/14 13:35:02.79 kernel ueshutdown: exitingYour format may not be quite like this as this example is from a 10.0.x SQL Server running on Solaris, but the section in red shows the critical error messages, the ninit: t_bind, Cannot assign requested address.
Another problem is if the interfaces file is missing either due to overzealeous pruning by a manic UNIX sa or by accident, check for the following in the error log
00:99/06/10 15:41:36.67 kernel Logging SQL Server messages in file '/opt/sybase/1103/install/errorlog'. 00:99/06/10 15:41:36.67 kernel kifpinfo: Could not stat interfaces file /opt/sybase/1103/interfaces, error = 2 00:99/06/10 15:41:36.67 kernel Could not open interface file '/opt/sybase/1103/interfaces'
Although termed client side problems these may also occur on the server! The error messages seen here basically depend on the underlying libraries
| Have you specified the server name with the -S option, and is it spelled correctly, does the interfaces file in $SYBASE or where you specify with -I have an entry for the server you are trying to connect to. | |
| Check the operating system connectivity to the hostname of the machine where the server is that you are connecting to, can you ping the host, has the hostname been changed, you will have to reconfigure your interfaces file to reflect the new hostname/IP address. | |
Check the permissions on the interfaces file, is it readable to your user, check for
the following related OS errors
|
|
Check the format of the interfaces file -
|
|
| Possibly indicates the server is not running, check the server is running, then check the interfaces file entry is correct. | |
| A malformed service line in the interfaces file or using a sockets based interfaces file in a TLI environment. | |
| Check the permissions on /dev/tcp. (TLI only) | |
| Check your account details, username and password it is case sensitive. |
|
Have you specified the server name with the -S option, and is it spelled correctly,
does the interfaces file in $SYBASE or where you specify with -I have an entry for
the server you are trying to connect to.
Also check that there is an interfaces file in the $SYBASE directory, it may indicate that the file is missing. |
|
|
Check the operating system connectivity to the hostname of the machine where the server
is that you are connecting to, can you ping the host, has the hostname been changed, you
will have to reconfigure your interfaces file to reflect the new hostname/IP address.
This may also indicate that the service line in the interfaces file may be malformed. |
|
| Check the permissions on the interfaces file, is it readable to your user. | |
| Check your user name and password, it will be case sensitive. |
| Version | Comments |
| 1.00 | Draft |
 |