Concept
The ProjectWise Gateway Server was developed to:
A Gateway Server is a ProjectWise Server that users connect through to get to other ProjectWise Servers. This server can be used to publish DataSources information from one or more Integration servers and provide routes to one or more ProjectWise servers.
The idea is that you can put Gateway servers around your network rather than building your network around ProjectWise. For example you could put a Gateway server in your DMZ to allow internet based users to connect to ProjectWise without exposing your Integration server directly to the internet. You could setup Gateway servers in your remote offices so all your users connect to a local server, that server then connects back to your main office. If you deal with several different Integration servers in several different locations you can configure your clients to point at one local Gateway server. That Gateway server would publish the Datasources from the different Integration servers and make the connections for the users.
*It is important to note that this document is focused on Gateway servers specifically, however, ProjectWise Caching and Integration Servers can also function as gateways to route ProjectWise traffic. Most of the concepts presented here can be applied directly to the other servers.
How it works
When a client starts, it looks at its ProjectWise Network Control panel to see if UDP is enabled and if it is pointing at any Servers on the DNS Services and Datasource Listing tabs. DNS Services is where the Gateway Server data is delivered to the client. The Client will poll any Servers listed on both of these tabs and any found via UDP (if UDP is not disabled) to download the [NameResolution], [Gateway] and [DB{x}] sections of the DMSKRNL.
With this data downloaded the client displays the Datasource list and waits for the user to make a connection to a server. Each time the client makes a connection to a server (be it to login or download a file) the client looks though its DNS cache (unless disabled) which includes anything delivered from the [NameResolution] section. The client then looks through the Gateway list for gateways or ‘non-direct paths’ to the server. By default the client will try to make a direct connection to a server however if it finds a gateway entry for a server it will route its traffic through that Gateway.
When the Client looks through its gateway list, it looks for an exact match between the server the users is trying to access and an item in the list. IE FQDN = FQDN (fully qualified domain name), shortname = shortname. A FQDN will not equal a shortname so don’t mix and match. If it does not find an exact match then the Client will make a direct connection to the Server. Mixing shortnames and FQDNs is the number one reason gateways / temporary caching doesn’t work for people.
*There are a few places in the newer versions where this doesn’t hold true (shortname will equal a FQDN) but it’s still a bad idea to mix the two. Take the time to make your configuration consistent.
When a user tries to download a file the client requests the storage location from the Integration server; Storage Area server name and file path. The Storage Area server name that the client gets is the one entered in PW Admin for the Storage Area. So if you setup [gateway] entries for any servers hosting storage areas you need to match the endpoint name to the name shown as the Storage Area server name in PW Admin. If you find you have a mix of name types (shortnames, FQDNs, IP addresses) you can always change the names in PW Admin to make things consistent.
How It’s Configured
To start we will focus on just setting up the gateway configuration, we will look at Publishing DataSource second and Temporary caching third. Throughout setting up your Gateway server you will need to provide the names of other servers. You should always use FQDN if your network supports it. Almost all networks do support FQDN, your IT group should be able to help with this. No matter what you do, stay consistent, if you start with FQDN’s stay FQDN, if you start shortname stay shortname, this cuts down on confusion later.
Bentley strongly recommends the use of FQDN names throughout your ProjectWise Implementation.
Gateway Configuration
Depending on the version of ProjectWise you have there are 3 to 5 different sections of the DMSKrnl.CFG that you need to configure for a Gateway server.
The [System] section provided an option as of SS4 RU called DisableClientDNSCache which allows you to disable ProjectWise DNS lookup caching on the client (this does NOT affect Windows DNS Caching). By default ProjectWise Explorer will cache the response to all DNS requests it makes as well as the IP address the Server tells the client it’s running on. The only way to clear this cache is to close the client and re-launch it. This can become a problem if the server is hosted in a cloud environment where its address could change unexpectedly or the IP address the server tells the client is different from the address the client should use for that server. It is generally recommended to set this however there are some ‘non-best practice’ configurations that this will break which is why it is not set on by default.
The [Name Resolution] and [Server Name Resolution] section provides Name Resolution much in the same way network DNS does however it is specifically for ProjectWise. This should not be used as a replacement for DNS but as a helper. Most of the time you do not need to populate the [Name Resolution] or [Server Name Resolution] at all as Windows will use network DNS to resolve everything. You also do not need to add entries for in the [Name Resolution] section for servers the client will be using the gateway to access. It really doesn’t matter to the client what the IP address of your integration server is if it will always use the gateway server to connect to it.
The [Gateway] section is only used by the client and provides first hop information on how to connect to a given endpoint. You only need to tell the client what gateway server to start with for any endpoint it needs to connect to. It doesn’t matter how may hops there are along the way, that’s handled by the [Routing] section.
The [Routing] section is only used by the server and helps the server determine its next hop and what port to use for that hop. For example if a gateway server (we’ll call it gatewayA) is providing access to an integration server (we’ll call it int-server). If there are no other ProjectWise servers in-between and it will use port 5800 then the route entry would look like “int-server=5800” (without the “”). If however there is another ProjectWise server in-between (we’ll call it gatewayB), you would need to list that as a next hop like this, “int-server=5800,gatewayB” (without the “”). In this example we are telling ProjectWise to connect to int-server use port 5800 and direct the traffic through GatewayB. GatewayB could be configured to then connect directly to the Integration server or though another Gateway server but none of that matters to gatewayA, gatewayA just need to know what our next hop is.
A note about V8i and later internet accessible Gateway servers. When a request is sent to any ProjectWise server, the server looks at who the request was sent to and what its name is based on how windows is configured. If its name matches the name the user requested then it answers the request. If the names do not match it will look for a route to the server you requested in the [Routing] section.
When a server is on the internet its real name and its internet name often do not match. For example the server’s windows name may be PWDMZ however on the internet you may have the external FQDN PW.COMPANY.COM set to resolve to the ProjectWise Gateway. This leads to a situation where the gateway server returns errors to the client because I doesn’t know it should be responding to requests for PW.COMPANY.COM.
* Note, take the time to get an external FQDN for your internet facing servers, configuring your clients to point at the public IP address can create several different problems and makes the server configuration much more complicated.
Pre SS1the best way to deal with this was to “rebrand” the server using the external FQDN. Under the [team mate] section in the DMSKrnl.cfg there are 2 configuration variables, ServerName= and ServerIPAddress=. This is commonly referred to the clustering config section or clustering section as it is used when you want to setup ProjectWise in a cluster. What these variables do is override the name and IP address that the server thinks belongs to it and allows us to give a new identity to the server. You would set the ServerName equal to the externally FQDN and the ServerIPAddress equal to the public IP address. You must also make an entry in the [Name Resolution] ( [Server Name Resolution] for SS1 and later) section for publicIP=FQDN. Once this is done and you restart the service the server will assume a new identity.
For SS1 and later the above still works however we have a new option that can provide some more flexibility. In the [Server Name Resolution] section we can set an alias for the server by setting server bind address = alternate name, IE 192.168.0.100 = PW.COMPANY.COM. With the clustering section you can only give the server one alternate name but with the server name resolution section you can give as many as you need.
Now the server bind address can be tricky, when ProjectWise starts on the server it ‘binds’ or attaches to the first network card it finds on the system and notes the primary IP address for the card as ProjectWise’s local IP address. If you have more than one network card on your system ProjectWise will not necessarily be bound to the NIC you might want it to. Also be aware that some system changes can change the binding order and the next time ProjectWise starts it will pick a new local address.
The binding order on each system is set on the “Network Connections” screen from the windows control panel. How you get to this screen depends on your version of windows, a quick search on your favorite engine should provide the correct steps. Once there you need to click on the ‘Advanced’ menu (on server 2008 and later systems pressing the ALT key will display the menus) and click ‘Advanced Settings’. The top frame on the screen displays the current binding order, to change the order click on an adapter and use the green arrows to move it up or down. When done press OK and restart the ProjectWise Service for the change to take effect.
There’s one more trick to know when dealing with the bind address and that is that ProjectWise provides a way to force the address you can bind to. If you force the bind address the binding order of the NICs is no longer important. Under the [Broadcast] and [Listener] sections of the DMSKrnl.cfg there is a ‘BindAddress’ and a ‘BindAddressIPv6’ that let you set the exact address ProjectWise binds to. If you’re not using IPv6, just ignore the ‘BindAddressIPv6’ line.
If you force the binding address however there are a few things to keep in mind. If the IP address of the system ever changes the ‘BindAddress’ will have to be update or the service will not start. When ProjectWise binds on its own it will respond to requests that come in on any NIC to any IP address. If you force the binding order you are telling ProjectWise to ONLY listen to requests on that address. If you have more than one address on that NIC or more than one NIC users will use to talk with ProjectWise that traffic will be ignored. If you are using a NAT firewall, requests sent to the public address that map to the server will work if you use the ‘BindAddress’ as NAT will translate the requests to the servers privet address.
There’s one last point to keep in mind for internet facing gateway servers when you are not using the clustering section. When a client requests the DataSourse listing and DNS services information from any ProjectWise server, the server tells the client its real name and IP address as part of the response. The client adds this information to its DNS cache and uses it for lookups later. If the server’s real name and external FQDN do not match there’s nothing to worry about. If however the serve’s real name and FQDN do match and ProjectWise is bound to an ip address other than the one the user should use to connect to the server (private ip address) your client will not work. This is because the client will use the ip address that the server gave it rather than the one it got from windows DNS. Pre SS4 RU the solution to this is to make sure the internal and external names do not overlap. SS4 RU and later you have a 2nd option, you can set DisableClientDNSCache which prevents the client from using the address the server gave it.
On SS4 and later you might has seen the [ServerGateway] section of the config, this is not used on Gateway Servers as Gateway’s handle others requests and do not make requests on their own. Storage Area Servers (also known as Caching servers) and Integration server can make calls to other Servers which by default go directly to another server. This setting allows those request to leverage Gateway server as long as the Gateway has an entry in the [Routing] section for the endpoint.
With these sections configured you’re Gateway should be up and running.
This is an example config from an SS3 gateway server setup as an internet facing gateway. The external FQDN for this server is pw.company.com. The comments in the file have been stripped for space but it is recommended to leave them in your file as they provide a handy reference when you are making changes.
[ServerNameResolution}192.168.0.100=pw.company.com[NameResolution};nothing for the client[Gateway]storageA.company.local=pw.company.comstorageB.company.local=pw.company.comstorageC.company.local=pw.company.comint-server.company.local=pw.company.com[Routing]storageA.company.local=5800storageB.company.local=5800storageC.company.local=5800int-server.company.local=5800,GatewayX.company.local
Publishing Datasources Configuration
To publish a Datasource we build upon the above configuration by first looking in the [team mate] section of DMSKrnl.cfg and finding ‘Databases=’. You must have an entry on this line for each Datasource you are going to configure below. For example, if you are going to setup three Datasources the line would look like this ‘Databases=db0,db1,db2’. If you are going to use ‘DSServer=1’ (well talk about that below) you only need one ‘db’ line for each a DSServer entry no matter how many Datasources that will return. Forgetting about the ‘Database=’ line is the number one reason people have trouble publishing Datasources.
Now we jump to the very bottom of the DMSKrnl.cfg, this is where each Datasource the Gateway will publish is setup. There are two ways of add Datasources to the list to be published. First is by listing each Datasource individually, the second is by using DSServer.
The individual list way of publishing DataSources only publishes the DataSources you have set in your list. This list can include links to as many different DataSources on as many different servers as needed. To individually list the DataSources you add the following 4 lines to the config for each DataSource you want to list.
[db{x}]
Description=<"Real" Datasource name on the Integration Server>
DisplayName=<Optional display name you want the clients to see>
Server=<Integration Server Name> (can not be a non-integration server)
The easiest way to get started is to copy the entries from your integration server and edit out what you don’t need. {x} would become the number of the DataSource starting at 0 and incrementing by one for each entry you make. IE [db0] [db1] [db3] etc. Information listed this way is delivered via the DataSource Listing tab in the PW Network Control Panel.
For Example
[db0]Description=MainDatasourceDisplayName=Main Datasource for Design DocumentsServer=int-server.company.local
The DSServer way of publishing DataSources pulls all the DataSoures listed on a given server. You can pull form as many different servers as needed. For DSServer you add the following 3 lines to the config for each server you want to pull DataSources from.
DSServer=1
server=<Any ProjectWise server> (will not pull DataSources published with DSServer from another box)
You add one entry per server no matter how many DataSources are listed on that server. {x} would become the number for each server starting at 0 and incrementing by one for each entry you make. IE [db0] [db1] [db3] ect. Information listed this way is delivered via the DNS Services tab in the PW Network Control Panel. If you use this method you can leave the DataSource Listing tab blank.
[db1]DSServer=1server=remoteserver.anothercompany.com
The benefit of the individual listed DateSources is the Gateway server does not need to pull anything before giving the client the DataSource list. This can speed up client launch by a few seconds depending on how many servers you are listing DataSources for and where those servers are located. This also allows you to only publish the DataSources you wish to for a given server and the ability to change their display name.
The benefit of DSServer is that it’s dynamic, so if you add or delete a DataSource on a server it will automatically populate for users connecting through the gateway server. Because this data is delivered with the DNS Services tab it reduces the number of client side entries that need to be made. DSServer can be pointed at non-integration servers to pull its list however will not pull DataSources listed on other servers by DSServer.
Temporary Caching Configuration
Temporary Caching allows a Gateway server to keep a local copy of a file as users download files from remote servers. This helps improve file access times for remote files as after the first full copy is pulled only a delta checksum and maybe some file deltas have to cross the wan link.
It is important to note that a Gateway Server can be a temporary caching server, but doesn’t have to be. A Temporary Caching Server must be a Gateway Server because a Temporary Caching Server can only cache the files that are routed through it.
For A Gateway server to be a Temporary Caching Server or host a Storage Area, in the DMSKrnl.cfg, under the [team mate] section, FileTransferSrv=1 must be set. Note, once FileTransferSrv=1 is set on a Gateway server it will require a Caching Server licenses.
To control Temporary Caching there is also a [cache] section in the DMSKrnl.CFG. Under this section you can set the following parameters.
enabled=true|false (required)
Setting enabled=true turns on temporary caching, if this is not present or set to false the server will not cache files.
servers=ipaddr1[:port1][,ipaddr2:port2,...]
This allows you to list the servers and optionally the ports for the servers you wish to cache files from. You would use this if you didn’t want to cache files from all server in your environment.
storagepath=path_to_cache_root (required)
This is the location on the Temporary Caching server where the cached files will be stored. You must create this folder. Under this fold ProjectWise will automatically create a number of different folders for its use. By default, files from each server you cache from will be stored in a folder named with the remote servers IP address and Port. IE 192.168.0.10-5800. If there is a need to change the IP address of a remote server you can preserve the cache by manually renaming this folder.
UseHostnameInPath = 1|0 (new to SS3, OFF by default)
New in SS3 is a way to force the folder cached files are stored in to be named by host name rather than IP address. So rather than the folder being named ‘192.168.0.10-5800’ it would appear as ‘StorageServer.domain.com-5800’. This can be useful if the IP address of the server you are caching from changed its address. If you are setting this on an existing Temporary Caching server you can rename the old cache folders from IP address to host name to retain the files you have already cached.
limit=xxx ; xxx=limit for cached files in megabytes (required)
This tells ProjectWise how much to cache on a server. This number is listed in megabytes with 1024 representing 1 GB. This value is often overlooked and set to low. Often users will use fetchfiles to pull down files over night and try to pull more files than the cache can handle. The results in users believing caching isn’t working correctly when in fact the cache is simply dumping just fetched files to make room for new ones.
purgebatchsize=1000 ; max # of files purged per pass, default 1000
This tells ProjectWise how many files to delete at a time when it reaches the cache limit. ProjectWise will delete batches of files until it gets under 80% used. In cases where you run close to your cache limit all of the time or in situations where you have very large or small files there can be some benefit to tweaking these settings however most users do not find the need to change this.
This caching example is specific to SS3 because of the UseHostNameInPath entry, with that remove it would work for any version of ProjectWise.
[cache]enabled=truestoragepath=c:\cache;cache up to 4gb of filelimit=4092UseHostnameInPath=1
Once you have the required settings in place and any optional settings you may want, you should be able to copy out a file with your client and see it in the cache. Remember, if your Storage Area server name and Gateway entries do not match (FQDN=FQDN, short=short) your client will not use the Gateway and the file cannot be cached.
For more info on gateway / caching servers and a sample configuration checkout http://communities.bentley.com/products/projectwise/content_management/w/wiki/5614.aspx