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:
| <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. |
| <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 |
| <ASCompilerOptimizationLevel> | (Since 1.6.1) Allows to tweak the optimization level of ActionScript extensions. The possible values are between -1 (no optimization) to 9 (max. optimization). By default this value is set to 9. If there are problems during runtime compilation you can try lower values or completely disable optimizations. We have found that it helps with very large extensions, when the compiler complains for the code size being too big. |
| <AutoReloadExtensions> | (Since 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. |
| <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 ) |
| <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 |
| <BanMode> | (Since 1.6.3, PRO only) Specifies if the auto-ban mode should work by user ip address or user name. (Default = ip address) |
| <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 |
| <DeadChannelsPolicy> | (Since 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. |
| <DebugIncomingMessages> | (Since 1.6.3) Logs all incoming client requests, useful for debugging. Never use in production |
| <DebugOutGoingMessages> | (Since 1.6.3) Logs all outgoing messages, useful for debugging. Never use in production |
| <DynamicPropertiesClass> | (Since 1.6.3) Allows to specify which class should be used for the User.properties and Room.properties Map object. By default a java.util.HashMap is used. You could for example change it to java.util.concurrent.ConcurrentHashMap or any other class extending java.util.Map |
| <EnableZoneInfo> | (Since 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. See this tutorial for more details |
| <ExternalPolicyFile> | (Since 1.6.1) This one overrides the previous policy settings by allowing to load and serve and external policy file. The file should be placed in the Server/ folder. |
| <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) |
| <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... |
| <H2EnginePort> | (Since 1.6.1) Allows to change the default TCP port (9002) used by the H2 database engine. NOTE: the TCP port is used exclusively by SmartFoxServer to communicate with the DB using the loopback address. (127.0.0.1) |
| <LogMaxFiles> | The maximum number of log files the server can create. |
| <LogMaxSize> | The maximum size of each log file before a new log file is created. |
| <Mailer> | Configuration of the SMTP server used for sending emails from extensions. You can check all details in this tutorial |
| <MaxMsgLen> | The maximum length of an incoming message. By default it is set to 4096 bytes (4 KBytes) |
| <MaxRoomVars> | The maximum number of room variables that can be created in a single room. -1 = unlimited |
| <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. |
| <MaxSocketIdleTime> | (Since 1.6.3) A interval (in seconds) which represents the maximum time a connection can stay idle before the server forces the disconnection. NOTE: This is valid only for client connections that still have to log in the server and create a User session. Once the user is logged in this parameter is ignored and the auto-disconnection is based on the MaxUserIdleTime parameter. |
| <MaxUserVars> | The maximum number of user variables that can be created by a single user. -1 = unlimited |
| <MaxWriterQueue> | The maximum number of messages that can be added to the outgoing message queue. This parameter is already set by default to a high value. |
| <PolicyAllowedDomains> | (Since 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> |
| <ServerIP> | It's the physical IP address used by the server. By default, since version 1.5.9, the server binds all the available IP addresses, so you don't need to specify an address. |
| <ServerPort> | By default SmartFoxServer listens on port 9339 for connections, but you can change this to any other value if your firewall is filtering this particular port number. |
| <UserVarsOptimization> | (Since 1.6.3) Allows to receive only real changes in user variables, avoiding variables that didn't change to be retransmitted. Improves bandwidth usage when many variables are being used. |
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
| buddyList (deprecated since 1.6) |
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" |
| 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 |
| 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. |
| 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. |
| 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. |
| 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. |
-> 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>
This is the full list of events that can be disabled: onJoinRoom, onUserEnterRoom, onRoomAdded, onRoomDeleted, onSpectatorSwitched, onUserCountChange, onUserLeaveRoom, onRoomLeft, onRoomCreateError, onJoinRoomError, onRoundTripResponse, onLogout
This is the full list of actions that can be disabled: joinRoom, autoJoin, addBuddy, clearBuddyList, createRoom, getRoomList, leaveRoom, loadBuddyList, removeBuddy, oundTripBench, sendObject, sendObjectToGroup, sendPublicMessage, sendPrivateMessage, setRoomVariables, setUserVariables, switchSpectator, getBuddyRoom
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>
-> Buddy Lists (new since version 1.6.0)
Since SmartFoxServer 1.6 the embedded "Buddy List Manager" provides two different modes:
The following tags can be used to configure the buddy list for each Zone:
| <BuddyList active="true/false"> | The main definition tag. You can toggle it with the active attribute. |
<mode> Can be basic or advanced, as described above <size> The maximum size of buddies for a buddy list. (Default = 50) <maxBuddyVars> The maximum number of Buddy Variables that each user can set. (Default = 10) <addBuddyPermission>
(advanced mode)Can be true/false. If true it will require that on each "add buddy" request the target buddy confirms or rejects the operation. <permissionTimeOut>
(advanced mode)Specifies the number of seconds after which a the "permission" request (see previous option) will time out. <mutualAddBuddy>
(advanced mode)If set to true it will mutually add the requester to target buddy list and vice-versa. This can be useful in conjunction with the next option and the "permission" feature to create a highly secure buddy list system.
Example:
- User A sends an "add" request to User B
- User B authorizes it
- User B is added to User A's buddy list and vice-versa
<mutualRemoveBuddy>
(advanced mode)If set to true it will mutually remove the requester to target buddy list and vice-versa when a client removes a buddy from his list.
Example:
- User A removes User B from his buddy list
- User B is auto-removed from user A list
<offLineBuddyVariables>
(advanced mode)Can be true/false. It activates the off-line Buddy Variables. The off-line variables are transmitted to the clients even when the target buddy is not online. They can be useful for keeping persistent properties about each buddy (such as an image, rank, country etc...) <persisterClass>
(advanced mode)With this tag you can specify the fully qualified name of your custom Buddy List persister class. For more details consult the javadoc. <ownerListFullErrorMsg>
(advanced mode)A custom error message sent to the client when his buddy list is full. (Since 1.6.6) <targetListFullErrorMsg>
(advanced mode)A custom error message sent to the client when the target user's buddy list is full. This can happen when the mutualAddBuddy feature is turned on and the target has no free slots in his buddy list. (Since 1.6.6) <maxBuddyVariableLen>
(advanced mode)Limits the maximum length of BuddyVariable values, default is 255 characters (Since 1.6.9)
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:
| 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. |
| 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) |
| isPrivate | Accepts a boolean value. If true a password will be needed to access the room |
| 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 |
| maxSpectators | The maximum amount of spectators for a game room. |
| 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. |
| name | It's the room name. Duplicates are not allowed in the same zone. |
| pwd | The room password. (Empty for no password) |
| 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, myExtension.py etc...) NOTE: for Java extensions you must use the fully qualified class name, e.g. com.test.MyExtension (do not add the .class at the end) |
| type | "script" for ActionScript extensions, "python" for Python extensions, "java" for Java extensions |
| doc index |