2.1 Configuration: the basics
The server configuration is saved in an XML file called "config.xml",
located in the Server/ folder.
By
opening the config.xml file you will notice that it is divided
into two main sections called <ServerSetup> and <Zones>: the first contains general settings for the server and the second defines
each application (zones) running in the server.
» | Server configuration |
» | Zone configuration |
» | Room configuration |
» | Extension configuration |
» Server setup
Below follows a description of
each XML tag in the <ServerSetup> section:
<ServerIP> | it's the IP address used by the server. You can change to match your server IP address |
<ServerPort> | By default SmartFoxServer listens on port 9339 for connections, but you can change thisto any other value if your firewall is filtering this particular port number. Please remember that port values below 1024 are only allowed by the Flash Player version 7.0.19.0 or later |
<AutoSendPolicyFile> | If set to TRUE it allows SmartFoxServer to automatically generate a
cross-domain policy file to enable Flash player 7 (7.0.19.0 or later) to connect outside the current domain. Only needed if your SWF files and the server are located in different domains. ( read more about it in chapter 3.1 ) |
<PolicyAllowedDomains> | (Available from version 1.4.0) You can specify a list of allowed domains for the cross-domain policy file. An example: <PolicyAllowedDomains> <AllowedDomain>gotoandplay.it</AllowedDomain> <AllowedDomain>smartfoxserver.com</AllowedDomain> </PolicyAllowedDomains> |
<MaxUserIdleTime> | The time is expressed in seconds and it represents the maximum time
allowed for an idle client. After that time, idle users are automatically disconnected by the server. |
<MaxRoomVars> | The maximum number of room variables that can be created in a single room. -1 = unlimited |
<MaxUserVars> | The maximum number of user variables that can be created by a single user. -1 = unlimited |
<LogMaxSize> | The maximum size of each log file before a new log file is created. |
<LogMaxFiles> | The maximum number of log files the server can create. |
<FileLoggingLevel> | Defines the importance level of the Server messages outputted in the
log files. There are 7 levels of logging depending on the importance of the log message, some of them are just internal notifications useful for debugging and others are very important messages that indicate application warnings and errors. The levels are: FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE By default the FileLoggingLevel is set to WARNING to help administrators find misbehaviours in the server, bad client requests etc... |
<ConsoleLoggingLevel> | Same as above but log messages are redirected to the operating system
console. By default the console logger shows "INFO" or higher level messages. By changing this value to a lower importance level like "FINE" you can debug your applications with more details for each server action. We reccomend to use "INFO" levels for production servers and lower values for local testing/debugging |
<BanDuration> | It specifies how much time a user will not be able to login once it
is banned. Expressed in seconds For example 60 = 1 minute, 3600 = 1 hour |
<BannedLoginMessage> | A custom message that is sent to a banned user that is trying to log in |
<AdminLogin> | The server administrator login name |
<AdminPassword> | The server administrator password. The password must be at least 6 characters
long and we reccomend to use alphanumeric characters and numbers mixed
together for better security. NOTE: The password sent by the client Admin tool is always encrypted |
<AdminAllowedAddresses> | For higher admin security you can restrict the IP addresses allowed
to connect as administrators. You can specify any number of allowed addresses. If you wish to bypass this restriction just use <AllowedAddress>*.*.*.*</AllowedAddress> to allow any IP address to log in as administrator. |
<ExtensionRemoteDebug> | By default it is set to true. When turned on, this option will enable the AdminTool to receive all trace messages coming from the server side extensions (SmartFoxServer PRO only) |
<Mailer> | Configuration of the SMTP server used for sending emails from extensions. You can check all details in this tutorial |
<AutoReloadExtensions> | (since version 1.5.0, PRO only) Globally enable/disable the auto-reload feature for extensions: the server will reload extensions as soon as they are modified. While this feature is useful for development it should be turned off in production environments. |
<EnableZoneInfo> | (since version 1.5.0) Enable / disable the ability to ask the server how many clients are currently connected in a Zone. The request can be done with any external application done in PHP / ASP / JSP or even Flash. No APIs or authentication is required. TODO: See this tutorial for more details |
<DeadChannelsPolicy> | (since version 1.5.0) Specify the server policy for dead / closed socket channels. Two modes are available: normal: allows unexpectedly closed or stalled socket connections to live longer in memory. strict: (recommended) uses a more efficient way to catch unexpected disconnections or closed channels. Immediately gets rid of closed channels, releasing their resources. |
<RawProtocolSeparator> | (Since version 1.5.5) Specify a the character used as a separator for the Raw/String protocol. By default the server uses the % character |
A Zone represents one application
(a chat, a game etc...) running in the server. SmartFoxServer can run many Zones simultaneously, each one independent from the others and with their own server side logic.
Usually each zone has at least
one room defined in its configuration that will allow users to connect and
see each others.
Since rooms can also be created dynamically with a client or server request you need
to define here only those that are needed by default in your application.
For example a simple chat could just start with one "Main Lobby" room and then allow clients to create their own custom rooms.
If you look at the default settings in the <Zones> section you will find that each zone is defined in a <Zone> block and rooms are nested inside of it.
Here follows a list of attributes for each <Zone> block
name | It's the name of your application. The zone name must be unique and you should also try to keep it short avoding long names since this attribute is at times sent in the server messages. |
uCountUpdate | Can be "true" or "false". It toggles the "User
Count" messages sent by the server to all clients in the zone. These messages contain updates about the number of users and/or spectators in each room of the zone, allowing to monitor in realtime the capacity and status of each room. If you don't need this feature you should turn it off to save bandwidth. Also if your application has a medium to high traffic (say at least concurrent 500 users) you may want to turn this option off to reduce the amount of messages sent to the clients. |
maxUsers | You can limit the maximum number of concurrent users allowed in each application. This way you can optimize the bandwidth available when more than one applications (zones) are running the server. |
maxRooms | It is possible to limit the amount of rooms for each zone. By default this value is set to -1 which indicates that there's no limit to the number of rooms. |
maxRoomsPerUser | This value sets the maximum number of rooms that each user can create at once. Default is 5 |
buddyList | Can be "false" or a positive number. In the second case you can turn on the buddy list feature by specifying the maximum number of buddies in each client list. The buddy lists are persistent and they are saved on disk in the "Sever/buddyLists/" folder. |
emptyNames | By default if the login name is empty an automatic username is created by the server using the format "Guest_" + autoincrement number. You can switch this option off by setting emptyNames = "false" |
roomListVars | By deafult is set to false. If you set it to "true" you will receive all the room variables for each room in the zone when requesting the room list. |
-> Moderators can be defined in each zone:
<Moderators status="on"> <Mod name="simon" pwd="simon" /> <Mod name="luke" pwd="luke" /> </Moderators>
By using the the status attribute you can toggle the moderators in each zone. Each <Mod /> tag defines the username and password for each moderator. Moderators have special commands for kicking and banning other users. (check the "Custom Login" tutorial for more details)
-> Disabling System Events and System Actions (version 1.4.0 and higher)
It is possible
to disable certain specific server events or actions by simply including them in the <DisabledSysEvents> and <DisabledSysActions> tags.
<DisabledSysEvents> <event>onRoomDeleted</event> <event>onRoomAdded</event> </DisabledSysEvents> <DisabledSysActions> <action>createRoom</action> <action>joinRoom</action> </DisabledSysActions>
These settings can be used to secure your application from unwanter requests and to optimize the bandwidth usage. An in-depth view of this feature can be found in "The new SmartFoxServer 1.4 Framework" article.
-> Filtering user names and room names (version 1.4.0 and higher)
Each Zone can have different rules about user names and room names. They can be limited to a certain number of characters and they can be filtered to avoid unwanted characters. The following tags allow to control the names:
<UserNameAvoidChars> | A sequence of characters that should be stripped from the user name. Example: <UserNameAvoidChars><![CDATA[,.:]]></UserNameAvoidChars> This will strip all the . , : (period, comma, colon) from user names |
<RoomNameAvoidChars> | A sequence of characters that should be stripped from the room name. Example: <RoomNameAvoidChars><![CDATA[,.:]]></RoomNameAvoidChars> This will strip all the . , : (period, comma, colon) from room names |
<MaxUserNamesLen> | The max number of allowed characters for a user name |
<MaxRoomNamesLen> | The max number of allowed characters for a room name |
-> Automatic reloading of extensions (version 1.4.5 and higher)
You can decide which Zones should have their extension(s) reloaded as soon as they get modified.
This feature can be very useful during the development and testing phases however it is recommended to turn it off when in production.
<AutoReloadExtensions>true</AutoReloadExtensions>
Each room is defined in a <Room> block and you can also
add a <Vars> section to declare room variables that should
be created when the room is initialized.
Below you'll find the list of attributes for defining rooms:
name | It's the room name. Duplicates are not allowed in the same zone. |
isPrivate | Accepts a boolean value. If true a password will be needed to access the room |
password | The room password. (Empty for no password) |
isGame | Can be "true" or "false". If true the room has some special features for games, like player indexes and support for spectators (users that can see the game without interacting) |
limbo | Limbo rooms are special rooms that can contain hundreds or thousands of clients that don't need to interact directly with each other. This type of room can be useful when the client needs to interact with the server, without the need to know the list of all the other users, their variables, etc... When the limbo flag is turned on, the room suppresses certain events (new user arrived, user left, user count changed, room and user variables) and inhibits the ability to send public messages. This way the room can handle thousands of clients without generating too much traffic and saving bandwidth. If clients need to communicate with each other they can use private messages, which don't need to be broadcasted to all other users. You can check this tutorial for in-depth look on this feature |
maxUsers | The maximum number of users that can join the room simultaneously. We reccomend using any number between 2 and 50. Allowing more than 50 users in a chat room can be a problem as many messages are received at once and it becomes difficult to follow the discussions. |
maxSpectators | The maximum amount of spectators for a game room. |
autoJoin | Can be true or false. By default it is set to false. It sets the current room as the default for the autoJoin() command used on the client side. |
uCountUpdate | Specifies if you want to receive the uCount updates in this room. By default it is TRUE for normal rooms and FALSE for game rooms. |
Room variables can be created as soon as the room is created. The following example shows how to define two room variables:
<Vars> <Var name="name" type="s" private="false">John</Var> <Var name="score" type="n" private="true">5500</Var> </Vars>
Each variable has these three properties:
name | the name of the variable |
type | the variable type ( s = string, n = number, b = boolean ) |
private | if true the variable cannot be modified by other users |
SmartFoxServer PRO enables you to write your own server
side logic and attach it to a Zone or Room.
Extensions can be simple .as Actionscript files or Java classes and you can
specify which extension(s) you'd like to use in your Zone or Room using the
following XML:
<Extensions> <extension name="dbTest" className="dbExtension.as" type="script" /> <extension name="dbTestAdv" className="dbExtensionAdv.as" type="script" /> </Extensions>
name | the name of the extension (it will be used by the client to refer to this extension. We reccomend using short names) |
className | the file name of the extension (e.g. myExtension.as for Actionscript or MyExtension.class for Java) |
type | "script" for Actionscript extensions, "java" for Java extensions |
doc index |