Configuring the TCP/IP Port Service - Firebird

By default, a Firebird server listens on port 3050 for TCP/IP connection requests from clients. Its registered port service name is gds_db. The good news is that, if you can go with these defaults, you have to do nothing on either server or clients to configure the port service.

You can use a different port, a different port service name, or both. You might need to do this if port 3050 is required for another service, for example, a concurrently running gds _db configured for a different version of Firebird or for an InterBase server. There are several ways to override the defaults. Both the server and the clients must be configured to override the port service name or number, or both, in at least one of these ways:

  • In the client connection string
  • In the command used to start the server executable
  • By activating the RemoteServicePort or RemoteServiceName parameters in firebird.conf (v.1.5 onward)
  • In the daemon configuration (for Classic server on POSIX)
  • By an entry in the services file

Before examining each of these techniques, it will be helpful to look at the logic used by the server to set the listening port and by the client to set the port that it should poll for requests.

How the Server Sets the Listening Port

The server executable has an optional command-line switch (–p) by which it can signify either the port number it will be listening on or the name of the port service that will be listening. At this point, if the switch is present, either port number 3050 or the port service name (gds_db) is replaced by the argument supplied with the –p switch.

Next—or first, if there is no –p switch—a v.1.5 server checks firebird.conf to look at the parameters Remote Service Name and RemoteServicePort:

  • If both are commented with #, then the defaults are assumed and no further change occurs. Any –p argument stands and the “missing” argument remains as the default.
  • If Remote Service Name has been uncommented, but not RemoteServicePort, then the port service name is substituted only if it has not been overridden already by the –p switch.
  • If RemoteServicePort has been uncommented, but not RemoteServiceName, then the port number is substituted only if it has not been overridden already by the –p switch.
  • If both Remote Service Port and Remote ServiceName are uncommented, then RemoteServiceName takes precedence if it has not already been overridden by a –p argument. If there is already a port service name override, the Remote Service Name value is ignored and the RemoteServicePort value overrides 3050.
  • At this point, if an override of either the port number or the service name has been signaled, both v.1.0 and v.1.5 servers proceed to check the services file for an entry with the correct combination of service name and port number. If a match is found, all is well. If not, and the port service name is not gds_db, the server will throw an exception and fail to start. If gds_db is the port service name and it cannot be resolved to any other port, it will map to port 3050 automatically.

If the default port number or service name is to be overridden, then you may need to make an entry in the services file. To understand whether it will be necessary with your override choices, follow through the steps outlined later in the chapter in the “Configuring the services File” section.

Using the –p Switch Override

Starting the server with the optional –p switch enables you to override either the default port number (3050) or the default port service name (gds_db) that the server uses to listen for connection requests. The switch can override one, but not both. From Firebird 1.5 onward, you can use the –p switch in combination with a configuration in firebird.conf to enable an override to both the port number and the port service name.

Syntax for TCP/IP

The syntax pattern for commands is

server-command <other switches> -p port-number | service-name

For example, to start the Superserver as an application and override the service name “gds_db” with “fb_db”, use this:

refbserver -a -p fb_db

Or, to override port 3050 to 3051, use this:

fbserver -a -p 3051

Syntax for WNet Redirection

On a WNet network, replace the preceding –p switch argument syntax with the following “backslash-backslash-dot-at” syntax:

fbserver -a -p \\.@fb_db

or

fbserver -a -p \\.@3051

Classic on POSIX:The inetd or xinetd Daemon

With Firebird Classic server on Linux or UNIX, the inetd or xinetd daemon is configured to listen on the default port and broadcast the default service name. The installation script will write the appropriate entry in the configuration file /etc/inetd.conf or /etc/xinetd.conf.

Problems attaching to a Classic server are often due to missing or bad port service entries in this file. You can check the current entry by opening it in a plain text editor (e.g., vim), and editing it if necessary. The following is an example of what you should see in xinetd.conf or inetd.conf after installing Firebird Classic on Linux:

If you configured the port service to be different to the defaults, you will need to alter xinetd.conf or inetd.conf accordingly. Restart xinetd (or inetd) with kill -HUP to make sure the daemon will use the new configuration.

Using a Configuration File Parameter

From Firebird 1.5 onward, you can configure either RemoteServiceName or RemoteServicePort in firebird.conf to override either the default port number (3050) or the default port service name (gds_db) that the server uses to listen for connection requests.

The engine will use one RemoteService* parameter, but not both. If you configure both, it will ignore RemoteServicePort in all cases, except where the server start command was invoked with the –p switch supplying an override to the port service name.

Thus, you can use the –p switch and a RemoteService* parameter, in combination, to override both port number and service name.

If the default port number or service name is to be overridden, then you need to make an entry in the services file.

Setting Up a Client to Find the Service Port

If you set up your server with the installation defaults (service gds_db listening on port 3050), then no configuration is required. If the server is listening on a different port or is using a different port service name, the client application and/or its host machine need some enabling configuration to help the Firebird client library find the listening port.

The connection string used by a client can include information for polling the server’s listening port in various ways. Firebird 1.5 clients can optionally use a local copy of firebird.conf. Changes may also be needed in the client’s services file.

Using the Connection String

If only the port name or the service name has been reconfigured, then include the alternative port number or service name in the connection string. This works for all versions of Firebird.

Syntax for TCP/IP Connections

To connect to a database named server named hotchicken that is broadcasting on port 3050 with the service name fb_db, the connection string would be this for POSIX:

hotchicken/fb_db:/data/leisurestore.fdb

Or, if the service name is gds_db and the port number is 3051, this would be the connection string:

hotchicken/3051:/data/leisurestore.fdb

For Windows, the connection string would be this:

hotchicken/3051:D:\data\leisurestore.fdb hotchicken/fb_db:D:\data\leisurestore.fdb

Notice that the separator between the server name and the port is a slash, not a colon. The colon before yhe physical path string is still required.

Syntax for WNet Connections

On a WNet network, use UNC-style notation:

\\hotchicken@3051\d:\leisurestore.fdb

Or

\\hotchicken@fb_db\d:\leisurestore.fdb

If the server’s port number or service name is an override, then you need to make an entry in the services file.

Using Port Syntax with Database Aliases

To connect through a non-default port with a database alias, affix the port number or service name to the server name, not to the alias. For example, suppose the database alias is stored in aliases.conf as

hotstuff = /data/leisurestore.fdb

Your application’s connection string for server hotchicken would be this:

hotchicken/fb_db:hotstuff

or this:

hotchicken/3051:hotstuff

Using a Copy of firebird.conf

From Firebird 1.5 onward, you can optionally include a client-side copy of firebird.conf in the firebird root directory and configure RemoteServiceName or RemoteServicePort to help the client locate the server port.

You can configure one of these two parameters to extend the override provided for the other one through the connection string (shown previously), or to override only Remote Service Name or Remote Service Port without using the connection string to do it.

If you need to avoid passing the port service name or the port number in the connection string, and the server is using non-defaults for both, you can configure both Remote Service Name and Remote ServiceP ort. You would use this technique if your client application needed to retain the capability to connect to InterBase or Firebird 1.0 servers.

Location of Firebird Artifacts on Clients

When you rely on firebird.conf on client machines, it is important that the client library knows where to find it. You will need to set up a Firebird root directory and inform the system of its location. Use the FIREBIRD environment variable to do this, in a manner similar to that described in Chapter Configuring Firebird for servers. Windows clients can alternatively use a Registry key. With a correct client setup, you can also make use of a local version of the message file. For more information, refer to the section “Installing Clients” in Chapter Firebird Clients.

Configuring the services File

You do not need to configure a service port entry for your Firebird server or clients if the server uses the installation defaults, gds _db on port 3050. If gds_db is the port service name and it cannot be resolved to any other port, it will map to port 3050 automatically. If you are configuring the service port for a different port or service name, both the server and the client must be explicitly updated to reflect the reconfiguration. On both Linux and Windows, this information is stored in the services file.

Locating the services File

Here are the locations of the services file on the different platforms:

  • On Windows NT/2000/XP, this file is located at C:\ winnt\system32\drivers\etc\services.
  • On Windows 95/98/ME, this file is located at C:\windows\services.
  • On Linux/UNIX, this file is located at /etc/services.

A services entry looks like this:

gds_db 3050/tcp # Firebird Server 1.5

Open the file using a text editor and either add a line or edit the existing gds_db entry, as follows:

  • For a Firebird 1.0.x server or client, alter either the service name or the port number to reflect how your server will start up.
  • For a Firebird 1.5 or higher server, edit or add a line, as required. If you have a Firebird 1.0 or InterBase server installed on the same host, retain the entries they require and add a new entry reflecting how the Firebird 1.5 server will start up.

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

Firebird Topics