You are on page 1of 847

REMBO: A Complete Pre-OS Remote Management Solution

REMBO Toolkit 2.0 Manual


REMBO: A Complete Pre-OS Remote Management Solution: REMBO Toolkit 2.0
Manual
Published August 2002

Rembo Technology SaRL, Geneva, Switzerland gratefully acknowledges the use of the
following third-party components:

Eric Young cryptographic software


This product includes cryptographic software written by Eric Young
(<eay@cryptosoft.com>). This product may include software written by Tim Hudson
(<tjh@cryptosoft.com>).

MD5 Message-Digest Algorithm


This product includes the RSA Data Security, Inc. MD5 Message-Digest Algorithm.

ZLIB data compression library


This product includes the zlib data compression library, copyright 1995-1998 by
Jean-loup Gailly and Mark Adler.

Rembo Technology SaRL, Geneva, Switzerland also acknowledges all trademarks and
registered trademarks referred to in this documentation.

• Microsoft, MS, MS-DOS, Win32, Windows and Windows NT are either registered
trademarks or trademarks of Microsoft Corporation in the United States and/or other
countries.
• Linux is a either a registered trademark or a trademark of Linus Torvalds in the United
States and/or other countries.
• Intel and Pentium are either registered trademarks or trademarks of Intel Corporation in
the United States and/or other countries.
• Unicode is either a registered trademark or a trademark of Unicode, Inc. in the United
States and/or other countries.
• UNIX is a registered trademark in the United States and other countries, licensed
exclusively through X/Open Company, Ltd.
• All other registered trademarks and trademarks are the property of their respective owners.
Table of Contents
REMBO concepts and upgrade procedure.............................................................i
REMBO Server Administration Manual............................................................. 12
REMBO Client Administration Manual ........................................................... 119
Rembo-C Scripting Reference Manual .............................................................. 157

i
REMBO concepts and upgrade procedure
REMBO concepts and upgrade procedure
Table of Contents
1. Rembo Concepts................................................................................................... 1
1.1. What is REMBO ? ...................................................................................... 1
1.2. How does it work ? ..................................................................................... 2
1.3. Client System Requirements....................................................................... 3
1.4. Server System Requirements ...................................................................... 3
1.4.1. DHCP server .................................................................................... 4
1.4.2. REMBO server................................................................................. 4
2. Upgrading from REMBO Toolkit 1.1 ................................................................ 5
2.1. New features in version 2.0......................................................................... 5
2.2. Upgrading the server................................................................................... 6
2.2.1. Upgrading a server running on Windows ........................................ 6
2.2.2. Upgrading a server running on Unix ............................................... 6
2.2.3. Enabling transparent filesystem on the server ................................. 7
2.2.3.1. Converting server’s filesystem on Windows ......................... 7
2.2.3.2. Converting server’s filesystem on Unix ................................ 8
2.2.3.3. What to do if conversion fails ............................................... 9
2.3. Upgrading client-side scripts ...................................................................... 9
2.3.1. Shared archives ................................................................................ 9
2.3.2. Device specific archives................................................................. 10
2.3.3. Functions added in version 2.0 ...................................................... 11

i
Chapter 1. Rembo Concepts

This chapter describes general network-boot and cloning concepts used in REMBO.

1.1. What is REMBO ?


REMBO is a PXE network boot application. A network boot application is different
from any other program for a number of reasons:

• It is invoked by the BIOS during the initial bootstrap of the computer, before any
operating system or disk boot manager.
• It depends on the presence of a special chip on the network card, the PXE boot
ROM.
• It is capable of communicating with a server over the network thanks to a
programming interface provided by the bootrom. PXE is the current de-facto
standard for this kind of programming interface.
• It is downloaded from a special boot server, and does not depend on any local
storage device. It can work on computers without hard disk, CD-ROM or floppy
disk devices. If a local storage device is present on the computer, it is accessible
to the network boot application. However, it will not fail if the storage device is
corrupted or broken.
• It gets its parameters (IP address and other boot parameters) from a central
DHCP server.

Once started, REMBO behaves like a mini-Operating System. It can perform


various operations depending on instructions written in scripts, embedded in HTML
pages or in simple text files stored on the server. These operations can be divided in
four categories : file, network, user interface and system. A complete list of the
operations for each of these categories can be found in Chapter 1 in Rembo-C
Scripting Reference Manual. Here is an overview of the most useful operations:

• User authentication. REMBO can allow or prevent access to the computer based
on the authentication credential entered by the user (typically: its password).
• OS-independent file access. Files can be created, copied, deleted, renamed and
so on. REMBO can access NTFS (Windows NT/2K/XP), FAT/FAT32 (Windows
95/98) and EXT2 (Linux) filesystems. File access happens before any operating
system is loaded, thus allowing modification of files normally locked or protected
by the operating system.

1
Chapter 1. Rembo Concepts
• HTML interface. REMBO features a complete HTML interface, with forms and
style sheets. Administrators can design the look of REMBO with almost no
limitation. Mouse-driven menus are also supported.
• Disk images. An optimized backup/restore feature is included in REMBO. This
feature can be used to clone operating systems on a large scale or to restore
unstable operating systems.
• Network filesystem. The server-side of REMBO is a powerful multi-threaded
application designed to run on several different platforms (Windows NT, Linux,
FreeBSD or Solaris). Files on the server can be loaded from the client computer
running REMBO using unicast or multicast (same packet sent to multiple
recipients) technology.
• Computer groups. Computers can be grouped together in the server
configuration file to share the same startup options and startup script/HTML
page. Each computer or group of computers can have its own options.

1.2. How does it work ?


A typical remote-boot sequence goes through the following phases:

1. Power on. The remote-boot computer is turned on, either by a user or by a


wake-up event.
2. Network boot. The computer is instructed to boot on the network, either by its
BIOS configuration (boot order), by a hotkey (e.g. F12) or by the wake-up
event.
3. IP address discovery. The remote-boot client broadcasts a DHCP request to get
an IP address. Any DHCP server that knows the client (i.e., recognizes its
hardware address) or that has a pool of freely distributable dynamic addresses
sends an IP address. The client takes the first answer and confirms it to the
server. In addition to the IP address, the server will give some other network
parameters to the client, and information on the boot procedure to follow.
4. Boot server discovery. In the case of PXE remote-boot, the client then
proceeds to the discovery of the boot server. The boot server will be responsible
for delivering a network boot program to the client. It is not necessarily the
same computer as the DHCP server. The client will answer to the first boot
server that replies, and download a small network boot program using a simple
multicast protocol (MTFTP).
5. NBP connection. If the network boot program is REMBO, the client will
establish a secure connection to the server, and get from the NBP service
parameters specifying how the computer should be configured, the group to

2
Chapter 1. Rembo Concepts
which the computer belongs to, whether I/O devices should be locked, what file
server and backup file server it has been attributed to and what is the startup
page to load.
6. Pre-OS configuration. REMBO will then download from the file server
everything required by the configuration specified by the system administrator.
These file transfers are done using a secure, robust and efficient multicast
protocol. Many actions can be performed to put the computer in a well-defined
state and ensure a failproof startup.
7. OS booting. When so instructed by the configuration, REMBO will remove
itself from the memory, and let the computer start the operating system, as if
the computer was booting normally from the hard disk. This ensure a full
compatibility with the operating system, and avoid all problems of the
traditional diskless remote boot.

As REMBO features a fault-tolerant server architecture, with the boot server always
available to the client. However, in case of severe network failure, REMBO clients
can be configured to work in off-line mode, that is, without network access.

1.3. Client System Requirements


The remote-boot clients should be equipped with a PXE-compliant bootrom, either
version 0.99 or 2.00. We strongly recommend to purchase flashable network cards
and to flash your bootroms with the latest available PXE release. Currently, the best
implementation of PXE is the one found in Intel’s network cards, since Intel is the
author of the PXE specification. 3COM, IBM and RealTek also provide a PXE
implementation.
At the time of this documentation is written, most computers come with built-in
network cards with native PXE support. Almost all PXE implementations are now
based on PXE 2.0 build 068-072, which is the last build released by Intel. If you
have a 3COM or Intel network card, there is no need to flash the PXE part of the
card because it is most likely that you already have the latest version. However, if
you have Realtek or SIS-based cards, it is recommended to flash the card with the
latest version available on the Internet to fix flaws discovered in the early versions.
If your network card does not support PXE, you can try to use Microsoft PXE boot
floppy, included in Microsoft Windows 2000 Server distribution. This floppy
emulates PXE for a limited number of network cards. Search for ’RBFG’ on the
Internet for more information.
REMBO’s graphical interface requires a VESA 1.1 compatible Video BIOS, and
the low-level disk access performs faster on BIOSes with Extended INT13 disk
support (support for hard disk larger than 8.4GB).

3
Chapter 1. Rembo Concepts
1.4. Server System Requirements
In order to use REMBO, you will need to setup a DHCP server and a REMBO
server. Both can reside on the same machine if desired.

1.4.1. DHCP server


There is no special requirement for the DHCP server. If the DHCP server and the
REMBO server are running on the same host, you must be able to define the Class
identifier DHCP option (option 60). REMBO can work with almost any RFC
compliant DHCP server, including Windows NT DHCP server, Windows 2000
DHCP server, ISC DHCP server, Solaris 7 DHCP server and the Netware 5 DHCP
server.

Windows 2000 and Linux’s RedHat 6.x both include a PXE server kit (DHCP
& BOOT services). You might want to disable some of these services in order
to run REMBO’s own PXE Boot server. If you want to still use these services,
you must then understand how PXE Boot Server Discovery works (as
described in the PXE 2.0 specification), and build a discovery infrastructure
with the built-in services.

1.4.2. REMBO server


The REMBO server can run on Windows NT, Windows 2000, Linux (for Intel-based
computers), FreeBSD and Solaris (for SUN Sparc computers). The linux binary has
been compiled on a RedHat 6.1 Linux distribution, and the Solaris binary has been
compiled on a Solaris 2.6 host. There is no special requirement for your server
hardware. You might want to store REMBO files on a large hard disk if you plan to
create many hard-disk images, and you might want to use a fast CPU if you want to
minimize the time spent creating these images (most of the compression work is
done on the server-side).
In practice, we do however recommend to have at least 256MB of main memory,
and a fast hard-disk (e.g. SCSI 10K RPM) in order to keep performance at a good
level.

4
Chapter 2. Upgrading from REMBO Toolkit 1.1

This chapter describes the upgrade procedure to follow in order to upgrade from
REMBO Toolkit 1.1 to REMBO Toolkit 2.0. If you are new to REMBO and you
have never installed REMBO Toolkit 1.1, you may still be interested in looking at
this chapter to see what has been added in the new version.

2.1. New features in version 2.0


REMBO Toolkit 2.0 introduces several new features that may impact on how your
upgrade process. This new version has been designed to be completely backward
compatible with version 1.1, but several features need to be explicitely configured
or upgraded in order to get the most from version 2.0.
On the server side, the following new features directly impact on how your server
works, and require special care:

• The old opaque server filesystem has been replaced with a new transparent
filesystem (i.e. files can be directly accessed and modified on the server without
having to upload or download files first). When upgrading, the server runs in
compatibility mode, until the filesystem is manually converted (see Section
2.2.3).
• Disk archives content is now stored in a shared repository, and archive files are
simply headers with links to content in the shared repository. When upgrading, a
new directory called shared is created on the server to store the shared repository.
Old archives are still usable as is, but new archives are automatically created
using the new format (see Section 2.3 in REMBO Client Administration Manual).

On the client side, the following new features directly impact your scripts and disk
images:

• Disk archive content is now stored in a shared repository on the server. Old
archives must be converted into new shared archives in order to use the repository
and to support new NTFS features (like NTFS compression).
• The NTFS driver has been rewritten to include support for compressed and
encrypted files. Disk archives created with version 2.0 must be restored on the
same NTFS filesystem version as the one used during the creation of the image.
For example, a Windows 2000 disk archive must be restored on a Windows 2000
partition.
• REMBO Toolkit wizards have been rewritten to focus on how to write scripts.
You can still use the old 1.1 wizards if required. All you have to do is to backup

5
Chapter 2. Upgrading from REMBO Toolkit 1.1
the file called rembo.shtml from your server before the upgrade, and upload it
back on the server after the upgrade.

2.2. Upgrading the server


Before starting the upgrade procedure, obtain a copy of REMBO Toolkit 2.0 from
our online shop, along with a valid 2.0 activation key. REMBO 1.1 activation keys
cannot be used with REMBO 2.0.
If you are currently using REMBO Toolkit 1.1 in a production environment, it is
advised to first try REMBO Toolkit 2.0 on a separate server in order to familiarize
with new features and convert your 1.1 deployment material to new format on a
case by case basis.

2.2.1. Upgrading a server running on Windows


This section gives important information for upgrading REMBO Toolkit 1.1 to
REMBO Toolkit 2.0 on a Windows server.
In order to perform the upgrade to version 2.0, you must first stop and uninstall your
current REMBO server. Use the server console to stop the REMBO service, and
then uninstall REMBO Toolkit using the Windows Control Panel. Uninstalling
REMBO will not delete files stored on your server. All data files and configuration
information will be preserved by this operation.
Once version 1.1 is uninstalled, install version 2.0 by running the InstallShield
executable provided by Rembo Technology. The installation process should detect
your old REMBO installation and propose you to upgrade this installation or
remove it. Choose upgrade, and follow instructions shown on your screen. At the
end of the installation, run the server console to check that your server is running
properly.

2.2.2. Upgrading a server running on Unix


If you are upgrading a server running on Linux, Solaris or FreeBSD, follow the
same steps as if you were installing a fresh new version (see Section 1.3 in REMBO
Server Administration Manual for more details):

• First stop any active rembo process on the server;


• Then uncompress and untar the distribution archive in the same directory as your
old installation;
• Then start your server in debug mode with ./rembo -d -v 4. If the server is
complaining about the activation key, make sure you have copied your 2.0
activation key in the same directory as rembo.

6
Chapter 2. Upgrading from REMBO Toolkit 1.1
• In a separate shell, upload 2.0 distribution files on the server. First edit
srvfiles.nc and set your server password, then run misc/netclnt
srvfiles.nc.

• Stop your debug server (with CTRL-C), and run your server in normal mode with
./rembo.

The format of the configuration file (rembo.conf) is the same for both version 1.1
and version 2.0. You do not need to change this file when upgrading to version 2.0.

2.2.3. Enabling transparent filesystem on the server


When upgrading from version 1.1, the server keeps the old opaque filesystem as a
backward compatibility with version 1.1. If downgrading to version 1.1 is not
needed anymore, the server filesystem must be converted into the new, transparent
filesystem. The new server filesystem has several advantages over the old, opaque
filesystem:

• More flexibility because server files can be modified without having to download
and upload the file in a temporary location;
• More robustness because backing up server’s files does not require stopping the
server.
• Easier usage because uploading and downloading files to and from the server is
as simple as a file copy.

Converting the server filesystem into the new format usually takes a few seconds,
because this operation consists in renaming files only. In order to convert the
filesystem, follow the steps for your operating system:

2.2.3.1. Converting server’s filesystem on Windows


If REMBO is installed on a Windows NT or Windows 2000 server, follow these
steps to convert the server’s filesystem:

1. open a command prompt window on your server;


2. change the current directory to REMBO’s installation directory:
c:
cd \program files\rembo server

3. stop REMBO service with the following command:

7
Chapter 2. Upgrading from REMBO Toolkit 1.1
net stop remboserver

4. start the conversion process with the following command. The process is
termined when a line containing Server filesystem structure conversion verified
is displayed on the screen.
rembo -d -v 4 -convert

5. stop REMBO by pressing on CTRL-C


6. start REMBO with the following command:
net start remboserver

When the conversion process is completed, use the Server Console to verify that the
server is running, and use Windows explorer to look at the content of files in the
REMBO directory. You should see a directory called global containing all your
server files. You can copy, rename, delete or modify these files without having to
use the Server Console.

2.2.3.2. Converting server’s filesystem on Unix


If REMBO is installed on Linux, Solaris or FreeBSD, follow these steps to convert
the server’s filesystem:

1. start a shell
2. change the current directory to REMBO’s installation directory:
cd /usr/local/rembo

3. stop REMBO service either by killing rembo processes, or with your favorite
init.rd script (make sure no instance of rembo remains alive)
/etc/rc.d/init.d/rembo stop

4. start the conversion process with the following command. The process is
termined when a line containing Server filesystem structure conversion verified
is displayed on the screen.
./rembo -d -v 4 -convert

5. stop REMBO by pressing on CTRL-C

8
Chapter 2. Upgrading from REMBO Toolkit 1.1
6. start REMBO again using your favorite init.rd script, or with the following
command:
./rembo

When the conversion process is completed, verify that the server is running, and
browse the content of files in the REMBO directory. You should see a directory
called global containing all your server files. You can copy, rename, delete or
modify these files without having to use the Server Console or netclnt.

2.2.3.3. What to do if conversion fails


If the conversion process fails, look at the error messages displayed on screen
during conversion. Most of the time, conversion fails because there are two
directories or two files in the old server filesystem with the same name but different
case (e.g. hosts and Hosts). Since the transparent filesystem is based on the
operating system’s filesystem, two files with the same name cannot be created. You
must first resolve these conflicts to let the conversion complete.
Conversion can be forced even if there are conflicts by using the -force
command-line argument. Conflicts will be automatically resolved by erasing one of
the two conflicting files.

2.3. Upgrading client-side scripts


The Rembo-C virtual machine implemented in version 2.0 is backward-compatible
with the 1.1 virtual machine. That means that scripts created on version 1.1 run
without modification on version 2.0. However, since archive format and archive
manipulation has changed, it may be required to update 1.1 scripts to use new
features implemented in version 2.0.
A list of functions and primitives added in version 2.0 is available in Section 2.3.3.

2.3.1. Shared archives


Shared archives have their content stored in a shared repository, either on the server,
or in the local cache partition. The advantage of shared archives is that the content
of the archive is shared between all archives, thus reducing the amount of space
needed on the server or in the local cache partition. Since all files with the same
content are stored only once, you can have several disk archives stored on the server
without having to use a large amount of disk space.
On the client-side, shared archive support is transparent as long as standard
functions like BuildDiskImage and RestoreDiskImage are used. Archives created

9
Chapter 2. Upgrading from REMBO Toolkit 1.1
with version 2.0 are automatically created as shared archives, even if Synchronize
is used. Archive creation is faster in version 2.0 when several archives are already
stored on the server, because the server will know most of the standard Windows
files, and a large part of the disk archive will not be uploaded on the server.
When restoring an archive with RestoreDiskImage or Synchronize, shared files are
automatically transferred from the shared repository on the server to the shared
repository on the local cache partition if the archive is not already in the cache
partition. However, if the archive has been downloaded in the cache partition (e.g.
using OpenArchive), shared files will have to be explicitely transferred from the
server to the cache partition with CopyCache. As a general rule, if you get a message
saying that a shared file is missing when restoring an archive, that means that you
have to explicitely download shared files for the archive you are restoring.
You can find more information about shared archives functions in Section 2.3 in
REMBO Client Administration Manual.

2.3.2. Device specific archives


With the introduction of the new NTFS driver, several modifications have been
added to the format of disk archives. One of them is of importance if you do not use
RestoreDiskImage to restore disk archives on client computers.

In order to be able to preserve most of the filesystem structure (i.e. file numbering,
file compression, cluster size, ...) when backing up and restoring a disk partition,
NTFS disk archives have become device specific. That means that an archive of an
NTFS filesystem created on a Windows 2000 partition can only be restored on a
Windows 2000 partition. This ensures that NTFS system or compressed files
contained in the archive will be recreated with the same format as in the original
partition that was used to create the archive.
In order to create a partition that is compatible with the filesystem contained in a
disk archive (e.g. Windows XP NTFS), the function DeviceCleanEx must be used
instead of HDClean. This extended version of the formatting function allows for an
additional parameter specifying device parameters to use to create the partition, as
the cluster size or the total number of files. The function DeviceGetInfo retrieves
this device information block from either a disk archive or a disk partition.
As an example, let us say that the first primary partition has been formatted in
NTFS under Windows XP, and the second primary partition need to be formatted
with the same format. The following command would format the second partition
using device information taken from the first partition:
var devinfo = DeviceGetInfo("disk://0:1");
DeviceCleanEx("disk://0:2",devinfo);

10
Chapter 2. Upgrading from REMBO Toolkit 1.1
As a second example, let us consider the case of a disk archive created on a
Windows 2000 NTFS partition containing compressed files. To restore this archive,
the destination partition must be formatted with the same device parameters as the
original partition. The device information block is taken from the archive and then
used to format the target partition.
var devinfo = DeviceGetInfo("cache://global/archive.img");
DeviceCleanEx("disk://0:1",devinfo);

2.3.3. Functions added in version 2.0


Here is the list of functions added in version 2.0. You can get a detailed description
of each function in Chapter 1 in Rembo-C Scripting Reference Manual.

• ClearProtectedPartitions, GetProtectedPartitions, SetProtectedPartitions,


GetBEER, SetBEER, GetBEEREntry, SetBEEREntry, HideProtectedPartitions,
UnhideProtectedPartitions, WriteRemboProtectedMBR;
• LoadDirMatch, BuildFileIndex, FileSetSize, RDLoad, StrFindCI;
• BatchTrans-
fer,CopyCache,InfoDownload,InitBatchTransfer,AddToBatchTransfer,
MoreBatchTransfer,InfoBatchTransfer;
• FileChoicePanel, BuildFileSelect, MakeWindow;
• ArchiveType, OpenArchDevice, CloseArchDevice;
• OpenShared, MarkShared, StatShared, SweepShared, CompactShared,
CloseShared, VerifyDLA, GetSharedSize;
• NTMapDevices, Win2KRegisterParts, Win2KChangeIPInfo,
Win2KChangeNameServers;
• LogonUser, AuthUser, AuthUserEx, GetNetPass;
• DeviceCleanEx, DevicePreAdapt, DeviceGetInfo, DeviceGetFsType;

11
REMBO Server Administration Manual
REMBO Server Administration Manual
Table of Contents
1. Rembo Server Installation .................................................................................. 1
1.1. DHCP server configuration......................................................................... 1
1.1.1. DHCP server and REMBO on different hosts ................................. 1
1.1.2. DHCP server and REMBO on the same host .................................. 2
1.1.2.1. Adding DHCP option 60 to Windows NT4 DHCP server.... 2
1.1.2.2. Adding DHCP option 60 to Windows 2000 DHCP server ... 3
1.1.2.3. Adding DHCP option 60 to a host with ISC DHCP server .. 3
1.1.3. Adding REMBO to an existing Boot Discovery infrastructure ....... 4
1.2. Rembo installation on Windows NT........................................................... 4
1.2.1. Installation........................................................................................ 5
1.2.2. Minimal configuration ..................................................................... 6
1.2.3. Testing the configuration.................................................................. 6
1.2.4. NT Service Troubleshooting............................................................ 7
1.3. Rembo installation on Unix ........................................................................ 7
1.3.1. Installation........................................................................................ 7
1.3.2. Minimal configuration ..................................................................... 8
1.3.3. Installing server files ........................................................................ 9
1.3.4. Testing the configuration.................................................................. 9
1.3.5. REMBO Server Command-Line Options...................................... 10
1.4. Troubleshooting ........................................................................................ 12
1.4.1. PXE bootrom not detected ............................................................. 12
1.4.1.1. Problem description ............................................................ 12
1.4.1.2. Problem resolution .............................................................. 12
1.4.2. The bootrom displays DHCP... and times out................................ 13
1.4.2.1. Problem description ............................................................ 13
1.4.2.2. Problem resolution .............................................................. 13
1.4.3. The bootrom displays MTFTP..., and an error message ................ 14
1.4.3.1. Problem description ............................................................ 15
1.4.3.2. Problem resolution .............................................................. 15
2. REMBO Server Configuration ......................................................................... 16
2.1. Concepts.................................................................................................... 16
2.1.1. Registry-based vs. file-based configuration ................................... 16
2.1.2. Parameters organization................................................................. 16
2.1.3. Minimal configuration ................................................................... 17
2.2. Global parameters ..................................................................................... 17
2.2.1. Parameters related to PXE ............................................................. 19
2.2.2. REMBO specific parameters.......................................................... 22
2.2.3. Configuration parameters related to fault-tolerance ...................... 24
2.3. Authentication domains ............................................................................ 24
2.4. TCP tunnels............................................................................................... 26
2.5. Host groups ............................................................................................... 27

i
2.5.1. The default group........................................................................... 28
3. Rembo Server Management Tools.................................................................... 31
3.1. Netclnt....................................................................................................... 31
3.1.1. Using NetClnt interactively ........................................................... 31
3.1.1.1. First step: connecting to a REMBO server ......................... 31
3.1.1.2. Second step: testing the connection .................................... 32
3.1.1.3. Third step: playing with the connection.............................. 32
3.1.2. Using NetClnt in batch mode......................................................... 32
3.1.2.1. Batch mode example........................................................... 32
3.1.3. Using NetClnt to manage the shared repository ............................ 33
3.1.3.1. Creating a duplicate repository ........................................... 33
3.1.3.2. Exporting shared files ......................................................... 33
3.1.3.3. Synchronizing shared repositories ...................................... 33
3.1.4. NetClnt command reference .......................................................... 34
3.2. Server Console .......................................................................................... 40
3.2.1. Introduction.................................................................................... 40
3.2.2. The Interface .................................................................................. 40
3.2.3. Adding a server .............................................................................. 41
3.2.3.1. Local Server ........................................................................ 41
3.2.3.2. Remote NT Server .............................................................. 41
3.2.3.3. Non-NT Remote Server ...................................................... 42
3.2.4. Server Status .................................................................................. 42
3.2.5. Starting the server .......................................................................... 42
3.2.6. Stopping the server ........................................................................ 43
3.2.7. Reloading the server configuration ................................................ 43
3.2.8. Modifying parameters.................................................................... 43
3.2.9. Modifying variables ....................................................................... 44
3.2.10. Browsing the log files .................................................................. 44
3.2.11. Accessing the server files............................................................. 45
3.2.12. Frequently asked questions .......................................................... 45
4. Rembo Enterprise Deployment ........................................................................ 46
4.1. Fault tolerance........................................................................................... 46
4.1.1. Fault-tolerance at the DHCP level ................................................. 46
4.1.2. Fault-tolerance at the REMBO level.............................................. 47
4.1.3. Synchronizing multiple REMBO servers ...................................... 49
4.1.3.1. Replicating the whole server filesystem blindly ................. 49
4.1.3.2. Server repository synchronization ...................................... 50
4.1.3.3. Selective transfer of server files .......................................... 51
I. Global parameters reference ............................................................................. 52
Backup ............................................................................................................. 54
BaseDir ............................................................................................................ 55
BootDiscoveryAddress .................................................................................... 56

ii
BootDiscoveryPort........................................................................................... 57
BootNoMulticastDiscovery ............................................................................. 58
BootReplyDelay............................................................................................... 59
DataDir............................................................................................................. 60
SharedDir ......................................................................................................... 61
DisableDHCPProxy ......................................................................................... 62
DisableBOOT................................................................................................... 63
DisableNBP...................................................................................................... 64
DisableFILE..................................................................................................... 65
DisableTCP ...................................................................................................... 66
FASTEncrypt ................................................................................................... 67
FASTPort ......................................................................................................... 68
MaxPCASTSessions ........................................................................................ 69
FileMCASTAddress......................................................................................... 70
FileMCASTEncrypt......................................................................................... 71
FileMCASTTTL .............................................................................................. 72
FileServerPort .................................................................................................. 73
TCPServerPort ................................................................................................. 74
Interfaces.......................................................................................................... 75
MaxLogSize..................................................................................................... 76
MTFTPClients ................................................................................................. 77
MTFTPMCastTTL........................................................................................... 78
MTFTPPort ...................................................................................................... 79
MTFTPStartDelay............................................................................................ 80
NBPServerPort................................................................................................. 81
NetPassword .................................................................................................... 82
II. Authentication domains reference................................................................... 83
AuthLocalDomain............................................................................................ 85
AuthNTDomain ............................................................................................... 86
AuthRadiusDomain.......................................................................................... 87
III. TCP tunnels reference..................................................................................... 88
RemoteHost...................................................................................................... 90
RemotePort ...................................................................................................... 91
IV. Host groups parameters reference ................................................................. 92
AuthDomain..................................................................................................... 94
FileServer......................................................................................................... 95
Host .................................................................................................................. 96
HostRange........................................................................................................ 97
PXEBootMode................................................................................................. 98
Lockout ............................................................................................................ 99
Options........................................................................................................... 100
RemoteConsole .............................................................................................. 102

iii
StartPage ........................................................................................................ 103
A. Sample configuration file ................................................................................ 104
B. Sample ISC DHCP 2.0 configuration file ...................................................... 113
C. Sample ISC DHCP 3.0 configuration file ...................................................... 115
Server parameters functions index..................................................................... 117

iv
List of Figures
3-1. The Server Console interface............................................................................ 41
3-2. The server status ............................................................................................... 42
3-3. Browsing the log files ....................................................................................... 44
3-4. Browsing the server files .................................................................................. 45

i
Chapter 1. Rembo Server Installation

This chapter explains how to install the server-side of REMBO. Go through the
instructions carefully, as every detail matters to have your remote-boot
configuration working properly. If the client computers are missing any
information, they will not be able to start.

1.1. DHCP server configuration


The DHCP server is used by the PXE bootrom the get its IP address and other basic
networking information (subnet mask, default gateway, ...). This document assumes
that you have already configured your network to use DHCP.
This section explains how to configure your DHCP server for one of the three
following situations:

• The DHCP server and the REMBO server are not running on the same host;
• The DHCP server and the REMBO server are running on the same host;
• You already have a PXE 2.0 infrastructure with PXE Boot Server discovery
installed and you want to add REMBO to the list of servers to discover.

If you are running BpBatch with PXE bootroms, do not reuse your BpBatch
DHCP configuration. Remove DHCP options 43 & 60 for hosts running
REMBO and follow the instructions given in this section (if you are running
REMBO on the same host as the DHCP server, you will need to set option 60
again).

1.1.1. DHCP server and REMBO on different hosts


Actions to perform

• If DHCP options 43 & 60 are set, remove them.

If the DHCP server is not running on the same host as the REMBO server, there is
no nothing to change in your DHCP configuration. The REMBO server will detect
DHCP packets sent over the network by PXE bootroms and will offer PXE
parameters without disturbing standard DHCP negotiation process (this behaviour
is called DHCPProxy).

1
Chapter 1. Rembo Server Installation

The REMBO server will only respond to discovery requests originating from
known hosts, that is, hosts declared in a host group in your server
configuration (see Chapter 2).
Since at this stage the client has no IP address (the REMBO server sends its
parameters during the DHCP negotiation phase), clients must be identified with
their hardware address in the Group statements.
If the REMBO configuration contains a Default group entry, then the server
will respond to all requests, including requests originating from unknown hosts.

1.1.2. DHCP server and REMBO on the same host


Actions to perform

• If DHCP option 43 is set, remove it;


• Set option 60 (Class identifier) to "PXEClient".

If you are planning to run the DHCP server and the REMBO server on the same
host, you will need to tell your DHCP server to send DHCP option 60 (Class
identifier) to the clients. Here are instructions for the most commonly used DHCP
servers (Microsoft DHCP server and ISC DHCP server):

1.1.2.1. Adding DHCP option 60 to Windows NT4 DHCP server


Adding option 60 to the Microsoft DHCP server (Windows NT 4.0) is a two steps
process. You must first create a definition for the option 60, because this option does
not exist in the server by default. Then, you can add this option to a group of hosts
(a scope) or to a single host.

Step 1. Add option 60 to the set of supported options


Go in DHCP Options/Default options and click on the New button. Add an
option called "Client Class", whose type is "String" and identifier is 60. See the
Figure 1-1.
Figure 1-1. Adding option 60

2
Chapter 1. Rembo Server Installation

Step 2. Add option 60 to a DHCP scope


Select the scope containing PXE clients (left part of the window) and go to the
menu DHCP Options/Scope. Add option 60 and set the value to "PXEClient".
You can add the option 60 to a single client by selecting the client in the
"Active leases" window, and by clicking on the "Options" button

1.1.2.2. Adding DHCP option 60 to Windows 2000 DHCP server


By default option 60 is not set under Windows 2000. If the Rembo server is running
on the same host as the DHCP server, you will have to add this option and set its
value to PXEClient in order to tell PXE clients where to find the Rembo server.
Here is how you can add option 60 with Windows 2000.

1. Open a command window (select START->RUN->CMD)


2. Type netsh
3. Type dhcp
4. Type server \\servername *OR* server ip_address

5. You should then see a command prompt that says: dhcp server>

6. Type add optiondef 60 PXEClient STRING 0 comment=option added for


PXE support

7. Type set optionvalue 60 STRING PXEClient

8. To confirm everything has been set correctly, type show optionvalue all

1.1.2.3. Adding DHCP option 60 to a host with ISC DHCP server


If you are using the ISC DHCP server 2.0, you can add the DHCP option 60 to a
group of hosts or to a single host by adding the statement option
dhcp-class-identifier "PXEClient"; to one of the sections of the configuration
file. If you were using option 43 (vendor-encapsulated-options) for BpBatch,
remove it for REMBO hosts.
A sample configuration file ISC DHCP 2.0 can be found in Appendix B.
The modifications to perform on a ISC DHCP server 3.0 are the same as for a 2.0
server, but the names differ:

3
Chapter 1. Rembo Server Installation
• Add vendor-class-identifier "PXEClient"; for the hosts running REMBO.
• Remove any occurence of option space PXE; if you were running BpBatch.

A sample configuration file ISC DHCP 3.0 can be found in Appendix C.

The REMBO server will only respond to discovery requests originating from
known hosts, that is, hosts declared in a host group in your server configuration
(see Chapter 2). You can specify either the IP address or the ethernet address
in the host list. At this stage the IP address of the remote-boot client is known.
If the REMBO configuration contains a Default group entry, then the server
will respond to all requests, including requests originating from unknown hosts.

1.1.3. Adding REMBO to an existing Boot Discovery infrastructure


If your network is already configured for PXE 2.0 Boot Server Discovery, all you
have to do is to add REMBO to your bootmenu. The identifier of REMBO Boot
Server is 15. If you want to use multicast discovery, use the multicast IP address
232.1.0.1.

An article in the knowledge base available on Rembo Technology’s website


describes how to configure PXE 2.0 Boot Discovery manually.

The REMBO server will only respond to discovery requests originating from
known hosts, that is, hosts declared in a host group in the server configuration.
But if the REMBO configuration contains a Default group entry, then the server
will respond to all requests, including those originating from unknown hosts.

1.2. Rembo installation on Windows NT


This section describes how to configure your REMBO server for standard operation
under Windows NT or Windows 2000. Instructions for configuring REMBO under
Unix can be found in Section 1.3. Before configuring your REMBO server, make
sure that your DHCP server is configured as described in the previous sections.

The installation executable must be run as a local Administrator, or with a user


with equivalent privileges.
REMBO comes pre-configured with the minimal set of options (mandatory
options). You might want to add new options, new groups or hosts at a later date.
The list of all options (basic and advanced) is available in Chapter 2. This list

4
Chapter 1. Rembo Server Installation
describes the options as found in the configuration file for the Unix version of the
server. However, Windows NT configuration items names are much the same as
their linux counterparts, and you should able to define new options and understand
them with the explanation given in Chapter 2.

1.2.1. Installation
To install the REMBO server, run the executable you have received when you
purchased REMBO. This executable will install REMBO in a directory of your
choice, and will perform basic installation tasks.
Once the installation process is finished, you should have the following files and
directories in your REMBO installation directory:

• rembo.exe: this is the server itselfs. Since the server is a NT service, you will not
need to execute this file directly, unless you are trying to run REMBO in debug
mode.
• files/: this is directory used by REMBO to store server files. You should not
need to modify any file stored in this directory.
• misc/: this directory contains miscellaneous files. In particular, it contains
netclnt.exe, a tool for modifying server files from the command line.

• logs/: this is where REMBO stores its log files. You can watch the files in this
directory at any time to check for error messages.
• sconsole.exe: this is the REMBO server console. See below for more details.
• rconsole/:this is the remote console application, used to remotely interact with
REMBO clients.

If you choose to use file-based configuration mode during the setup of the
REMBO server, please understand that you will not be able to use all the
functionalities of the server console. You should also read Section 1.3 as it
contains valuable information about the file-based configuration.
The setup application installs REMBO as a Windows NT service. You can check
that the service has been properly installed by searching for RemboServer in the list
of services (Click on Services in your control panel). At this time the service
should be started and running. If the service is not started, read Section 1.2.4.

If you need a high level of security, we recommend you to change the default
permissions of the registry key used by REMBO. By default, anyone can
access this key. Use REGEDT32 to change the permissions to something more
secure, but make sure that SYSTEM can read, write and create keys (this is the

5
Chapter 1. Rembo Server Installation
account used by the service) and that the user that runs the REMBO server
console can also read, write and create keys.
The REMBO configuration is stored in
HKLM/System/CurrentControlSet/Services/RemboServer/Parameters.

1.2.2. Minimal configuration


The installation process should have created a new group called Rembo Server in
your start menu, with two icons:

1. The REMBO server console;


2. The Remote Console application

Start the REMBO server console (as Administrator) by clicking on the appropriate
icon. You should see an icon for your local server. You can click on it, and browse
the sub-sections to familiarize with the console. Read Section 3.2 for a description
of the server console, and Chapter 2 for a detailed description of configuration
parameters.

1.2.3. Testing the configuration


When in the server console, click on your local server, then click on Status. The
right window will show the status of your server. If the status is not
SERVER_RUNNING, click with right button on the current status and choose Start
Service in the contextual menu. This should start the server, and you should see
SERVER_RUNNING after a few seconds. If the server is still not running, read Section
1.2.4.
Once your server is running, you can browse server files and watch logs from the
REMBO console. Experiment your installation by starting a PXE client. The
computer should start REMBO and display a welcome message. If it does not, look
at the logs on the server, and make sure that your DHCP server is configured for
answering to your PXE client. See Section 1.4 if the remote-boot client does not
start.

If you change a global parameter with the server console, you must stop, then
restart the server for the change to be processed by the server. However, if
you change one of the groups (or add a group) or one of the hosts (or add a
host), you can use the reload server command to tell the server to reload its
host/group configuration.

6
Chapter 1. Rembo Server Installation
To start, stop and reload the server, select status in the left window, then click
on the current status with the right button and choose a command to perform.

1.2.4. NT Service Troubleshooting


If your server does not start, or you suspect that something is going wrong, you
have several options to collect debug information from the server:

• Look at the NT Event Viewer. The REMBO server logs fatal errors messages
into NT event manager;
• If the service does not start, run rembo.exe from the command-line with the
following options: rembo -d -v 4. This will run rembo as a console
application, with all debugging output redirected to your command window. You
can increase the debuglevel (the -v parameter) to 6 for maximum details. See
Section 1.3.5 for more information about the command line arguments. If
REMBO complains about an error in the configuration, reinstall a fresh copy of
REMBO. If the error message is related to your network configuration, try to
solve it and run the server again. In particular, you should change the Interfaces
global parameter if your server has more than one network interface.
• If the service works but you want debugging information, set the advanced
option called GlobalDebugLevel to a value between 2 and 6 with the server
console. REMBO will write the debugging output in the log files stored in the
logs/ directory (you can view the log files from the server console as well).

If it still does not work, contact us at support@rembo.com.

1.3. Rembo installation on Unix


This section describes how to configure your REMBO server for standard operation
under Unix (Linux or Solaris). Instructions for configuring REMBO under Windows
NT can be found in Section 1.2. Before configuring your REMBO server, make sure
that your DHCP server is configured as described in the previous sections.
The REMBO server distribution package comes pre-configured with a default
configuration file. For the purpose of this chapter, we will only set up the minimal
configuration that allows the remote-boot clients to start. More sophisticated
configuration options will be discussed in Chapter 2.

7
Chapter 1. Rembo Server Installation
1.3.1. Installation
Choose the directory where you want to install the REMBO server (use for instance
/usr/local/rembo). Extract the content of the REMBO distribution package to this
directory. You should then have

• A program named rembo (the server);


• A text file named rembo.conf (the server configuration file);
• A text file named srvfiles.nc (the basic server files package);
• A subdirectory named misc, with miscellaneous files that you might need later
on;

1.3.2. Minimal configuration


Using your favorite text editor, open rembo.conf. Its content should be something
like:
# Basic Rembo Server config file
#

# BaseDir <string>
# Specifies the home dir for the server. All paths can then be
# specified as relative to this base directory
# e.g. Basedir "c:/bootrom/rembo"
BaseDir "/usr/local/rembo"

# NetPassword <string>
# This password is used by the Rembo server to protect its files
# agains an illegal use through the NETfs client (netclnt).
# This option is mandatory.
NetPassword "please set a password here"

#
# Default group. Hosts will take their parameters from this group.
# Unless you create other groups with hosts in it.
#
GROUP Default {
StartPage "net://global/rembo.shtml"
}

Many additional items can be specified in this configuration file. However, all you
need to configure for now is the path were you installed the REMBO server
(BaseDir), and a password for accessing server files with the netclnt utility
(NetPassword).

8
Chapter 1. Rembo Server Installation

We here assume that your REMBO server is in the same subnet as the
remote boot clients. If this is not the case, you will have to implement PXE
discovery in your DHCP configuration.

We also assume that your REMBO server has a single network interface. If
you have a multi-homed host, you will need to specify the interface on which
the boot server discovery takes place by using the Interfaces parameter.
You are now ready to start the server for the first time.

1.3.3. Installing server files


The REMBO server needs to have a minimal set of files on its filesystem for the
remote-boot client to start. These files are contained in the srvfiles.nc text file,
and the method to install these files in the server is described in this section.
You must first start the server by typing rembo -d -v 4 at the command prompt. If
the server complains about a syntax error in the configuration file, verify that you
did not forget to use double quotes around the network password and the base
directory, and that the base directory exists. During the first start, the server will
need an extra time for generating a random cryptography key.
Once the server is started and waiting for connections, edit the file srvfiles.nc,
and replace the line open 127.0.0.1 install (the first line) with open 127.0.0.1
xxxx where xxxx is the password you have set in the configuration file rembo.conf
(NetPassword parameter).
You can then run the command misc/netclnt srvfiles.nc in the installation
directory of the server. If NetClnt or the server complain about short packets, make
sure that the password in the first line of srvfiles.nc matches the password in the
rembo.conf configuration file. Several files should be transferred to the server, and
NetClnt should return to the command prompt after the last file is sent to the server.
Your server is now ready to receive requests from remote-boot clients. You can stop
the server, and read the following section.

1.3.4. Testing the configuration


From the directory in which the configuration file is stored, start the REMBO server
using the following command line: rembo -d -v 2. This will instruct the server
to report errors and warning messages to the standard output, and let you check that
everything is going well.

The REMBO server must be run as root, because it needs to access


privileged UDP ports. If you are running REMBO on the same computer as

9
Chapter 1. Rembo Server Installation
your DHCP server, the DHCP server must always be started first, because
REMBO needs to be able to detect whether a DHCP server is running at
startup.
Each of the server threads should display a banner message on the standard output,
and then wait for a client to connect. Ensure that there is no warning nor notice that
a service has been disabled. Possible pitfalls are:

• Starting the server without administrator (root) privileges, which prevents it to


reserve some port;
• Starting the server without write privileges in its base directory;
• Having another PXE Boot server running on the same computer, preventing the
REMBO server to reserve the PXE BINL port;
• Having a TFTP server configured on the same computer (check that the line with
tftpd in /etc/inetd.conf is disabled). This will prevent REMBO to serve the
bootstrap to remote-boot clients;
• Running REMBO on a computer without multicast capabilities, typically on a
computer with a loopback interface only;
• Running REMBO on a multi-homed computer (a computer with multiple
network interface cards) without specifying the Interfaces parameter.

If you have any warning, stop the server and try to fix it. Once the server is running
properly, turn on a client. After a few seconds, REMBO should be running.

1.3.5. REMBO Server Command-Line Options


The REMBO server can be started either manually or in a init.d script. It should
not be started by inetd.

rembo [-d] [-v loglevel] [-c configfile] [-convert] [-force] [-rehash] [-


readonly] [-chkshared] [-fixshared] [-statshared] [-sweepshared] [-packshared]

• -d : print debug info to the standard output, do not run as daemon (do not detach)
• -v : set the verbosity level (default: 2)
• -c : specify the config filename (default: rembo.conf)
• -convert : convert server’s filesystem from old compatibility mode to new
transparent filesystem (see Section 2.2.3 in REMBO concepts and upgrade
procedure).

10
Chapter 1. Rembo Server Installation
• -force : force filesystem conversion in case of filename conflicts during
filesystem conversion (to be used in conjunction with -convert).
• -rehash : force filesystem to recreate inode numbers for every file in the
filesystem. This option only works when the new filesystem is enabled.
• -readonly : run Rembo server in read-only mode. When running in this mode,
the server will not write to the shared repository. This option can be used on a
backup server, where filesystem content is regularly synchronized with a primary
server, but no changes are allowed on the backup server.
• -chkshared : initiate a verification process on the server shared repository. Errors
will only be reported, but corrections will not be applied. This operation can take
several minutes. During that time, no connection to the server is accepted.
• -fixshared : initiate a repair process on the server shared repository. Errors will
be corrected by deleting corrupted records. Note that this repair process is
automatically triggered when the server is killed with unflushed changes to the
shared repository. This operation can take several minutes. During that time, no
connection to the server is accepted.
• -statshared : initiate a complete analysis on the server shared repository, and
display a summary of shared files usage. This operation can take several minutes.
During that time, no connection to the server is accepted.
• -sweepshared : initiate a mark and sweep operation on the server shared
repository. Shared files not used in any archives on the server (as reported when
using -statshared) will be cleaned out. This can be used to recover disk space
on the server after deleting a significant number of disk images. This operation
can take several minutes. During that time, no connection to the server is
accepted.
• -packshared : initiate a mark and sweep operation on the server repository, then
shrink all shared repository files to their minimal size to recover any preallocated
storage. Note that the use of this function may lead to fragmentation of the shared
file repository, and its use is therefore not recommended unless the server
configuration is final and will not evolve anymore. This operation can take
several minutes. During that time, no connection to the server is accepted.

The verbosity levels are defined as :

• 0 : no output
• 1 : log error messages only
• 2 : log error and warning messages
• 3 : log error, warning and info messages

11
Chapter 1. Rembo Server Installation
• 4 : same as 3, but also log notice messages
• 5 : same as 4, with debug output
• 6 : same as 5, with network trace

The following command-line switches perform actions on the server, and must be
run from a command-line prompt when the server is stopped:

• convert
• chkshared
• fixshared
• statshared
• sweepshared
• packshared

As an example, here are the commands to type in a windows command-prompt to


recover disk space used by the shared repository after having deleted several disk
archives:
c:
cd \program files\rembo server
net stop remboserver
rembo -d -v 4 -sweepshared
[press CTRL-C when the sweep process is completed]
rembo -d -v 4 -packshared
[press CTRL-C when the sweep process is completed]
net start remboserver

1.4. Troubleshooting

1.4.1. PXE bootrom not detected

1.4.1.1. Problem description


During the boot process, there is no message about the PXE bootrom, and the
computer boots as usual (on the floppy, hard disk or CD-ROM).

12
Chapter 1. Rembo Server Installation
1.4.1.2. Problem resolution
First check that your network card is properly installed, and that a PXE bootrom is
installed on the network card (check the features list in the product documentation).
To verify that the network works, run Windows or Linux, and configure the
operating system so that you are able to ping other machines (or you are able to see
other machines in the network neighbourhood).
On certain network cards, the PXE bootrom may not be activated by default. Read
the product documentation to find the key combination to press to enter the PXE
setup menu at boot time. On Intel EPRO100, the key combination is CTRL-S, or
shift-shift (i.e. both shift keys pressed). These keys must be pressed during all the
boot process, when the computer is powered on. Some cards might not have a
configuration menu.
Then, enter your BIOS setup during boot time (DEL, or F2 key on most systems),
and configure the BIOS boot process so that the network card is the first entry in the
boot list. In some BIOS, there is an option to enable boot on network. On other
BIOS, you must manually set the LAN (also called NET, or Other) as the first
device of the boot order.
If all these steps fail, try to obtain a flash memory upgrade from your network card
vendor, and flash the network card rom with the newest upgrade. If the flash process
fails, there is chance that no bootrom is installed on your network card.
If you are still not seeing the PXE messages, then ask for support from your
network card manufacturer.

1.4.2. The bootrom displays DHCP... and times out

1.4.2.1. Problem description


The bootrom does not receive enough information to proceed further. Either the
DHCP server or the REMBO server is not properly configured.

1.4.2.2. Problem resolution


First check that your DHCP server is properly configured as explained in Section
1.1. In particular, check that option 60 is set to PXEClient if you are running the
DHCP server and the PXE server on the same host only.
If the DHCP server and the REMBO server are on the same host, try to stop both
servers, and restart the two servers in the following order: DHCP server first, then
the REMBO server. If the REMBO server is started first, it might reserve the DHCP
port, thus preventing the DHCP server to start.
Check your DHCP configuration: run Windows or Linux on your remote-boot
client, and configure the network to use dynamic configuration instead of fixed IP

13
Chapter 1. Rembo Server Installation
address. If this works (run winipcfg or ipconfig on a Windows computer,
ifconfig on a Linux computer), then the DHCP server is properly configured for
this host. Otherwise, check your DHCP server configuration, so that the
remote-boot client is assigned an IP address, a netmask and a default gateway.
If your server is properly configured (including option 60), and the client still
displays DHCP... followed by an error, check your REMBO server configuration.
Stop the REMBO server, then run rembo.exe -d -v 6, and start the remote-boot
client. When starting, the server should display a line saying whether it is acting as
a DHCP Proxy or a BINL Proxy. If the DHCP server and the REMBO server are on
the same host, the REMBO server should act as a BINL proxy. If they are on
different hosts, the server should act as a DHCP proxy. If the server displays a
message saying it acts as a BINL proxy, but the two servers are not on the same
host, it means that there is a DHCP server installed on the computer where you have
installed REMBO.
When a client starts, and DHCP is properly configured, the REMBO server (in
debug mode) should display Valid discovery from ... followed by Client ...
found in group .... If the server displays the first line, but displays Client ...
not found in any group instead of the second line, it means that your
configuration file does not contain a default group, and that the remote-boot client is
not declared in any group (the client must be declared with its hardware address, not
its IP address).
If the server does not display the message Valid discovery request from ..., it
means that the option 60 on the DHCP server is not properly set (see Section 1.1),
or the REMBO server and the DHCP server are not on the same subnet. If you have
installed REMBO on a multi-homed host (a computer with more than one network
card, or with a dialup adapter), use the Interfaces option to specify which network
interface to use.
If it still does not work, send a report to support@rembo.com with the following
information:

• All the files from the logs directory of the REMBO server;
• The configuration information for your DHCP server;
• The configuration information for your REMBO server;
• A dump of the network traffic between the servers and the remote-boot client.
Uses the MS Network Monitor on Windows NT/2000, and tcpdump on
Linux/Solaris (or snoop).

14
Chapter 1. Rembo Server Installation
1.4.3. The bootrom displays MTFTP..., and an error message

1.4.3.1. Problem description


The bootrom was unable to receive the REMBO bootstrap from the server.

1.4.3.2. Problem resolution


If the delay between the MTFTP.. message and the error message is very short, and
the message tells that a file was not found, it means that the computer you have
installed REMBO on already runs a TFTP server (and this TFTP server answers
request for the REMBO server). If you are using Windows NT/2000 on the server,
check the list of services, and disable services related to TFTP or Boot protocols
(Intel LCM, Microsoft PXE, ...). If you are using Linux/Solaris, check that no
process with tftp in the process name currently runs, and that the line with tftp in
the file /etc/inetd.conf is commented (add a # at the beginning of the line, and
restart inetd with kill -HUP on the process id of inetd).
If the delay between the MTFTP.. message and the error message is long, it means
that multicast TFTP datagrams sent by the REMBO server are not received by the
remote-boot client. Check that multicast is enabled in the kernel if you are running
Linux/Solaris at the server-side. If you have installed REMBO on a multi-homed
computer (a computer with more than one network card, or with a dialup adapter),
use the Interfaces parameter to specify which network interface to use for
multicast packets.
If it still does not work, send a report to support@rembo.com with the following
information:

• All the files from the logs directory of the REMBO server;
• The configuration information for your DHCP server;
• The configuration information for your REMBO server;
• A dump of the network traffic between the servers and the remote-boot client.
Uses the MS Network Monitor on Windows NT/2000, and tcpdump on
Linux/Solaris (or snoop).

15
Chapter 2. REMBO Server Configuration

This chapter contains an exhaustive description of the server-side configuration


parameters. Only a limited subset of these parameters is necessary for the everyday
operation of the REMBO server, and in most cases the only parameters to require
modification are the group and hosts parameters.

2.1. Concepts

2.1.1. Registry-based vs. file-based configuration


The internal storage of the configuration parameters differ between the Unix
(Linux, Solaris) implementation and the Windows NT implementation of the
REMBO server. On Windows NT, all the parameters are stored in the registry, so
that remote modification of the configuration is possible (the registry can be
modified from a remote authorized NT workstation). On Unix environments, all the
configuration is stored in a single text file, to accomodate with the common usage of
using a text file to configure a network service under Unix. Note that it is possible to
run the Windows NT version with a text file instead of the registry.
See Appendix A for an example of configuration file (file-based configuration
mode).

If you are using the registry-based configuration mode, you can use the
Server Console to access the configuration of your REMBO server. See
Section 3.2 for more information.

2.1.2. Parameters organization


Whether you are running the server with a configuration file or using the registry,
configurations parameters are always organized in three distinct groups: global
parameters, authentication domains and host groups.
Global parameters are configuration options defining the low-level configuration of
the server. These parameters can be divided in four parts:

• global parameters common to all services;


• global parameters related to the PXE boot process;
• global parameters for the Rembo specific services;
• and global parameters for fault-tolerance.

16
Chapter 2. REMBO Server Configuration
Authentication domains are used to group authentication parameters under a same
name. This name can then be used in Rembo-C scripts to check the identity of the
user at the boot level.
Host groups define a list of hosts and a set of parameters specific to these hosts.
This can be used to group hosts together if they share the same configuration
information (for example the same startup page). Each group parameter can be
overriden at the host level, thus making the configuration very flexible.
TCP tunnels define gateways between REMBO client and remote TCP resources,
like a mail server, or a database server.

Any modification to global parameters requires a complete restart (stop the


process, then start again) of the server, because global parameters define
low-level information that cannot be changed dynamically.
Modifications to authentication domains, TCP tunnels and host groups only
require a soft restart (restart action with the server console, or kill -HUP under
Unix) of the server to be effective.

2.1.3. Minimal configuration


When the REMBO server is installed for the first time, only a very limited subset of
the configuration is present. This subset includes the two basic parameters BaseDir,
NetPassword, no authentication domains, no TCP tunnel, and a single host group
called Default. This is the minimum configuration information required to start the
REMBO server.
If you have choosed to run the server in file-based configuration mode, you will
have to set the two parameters BaseDir and NetPassword by editing the
configuration file rembo.conf before starting the server for the first time. BaseDir
must contain the directory where REMBO has been installed, while NetPassword
should be set to the password you have choosed to protect your REMBO network
files against illegitimate access. Once these two parameters are set, you can start the
server to check that everything is working properly.

2.2. Global parameters


As noted previously, global parameters are needed for the REMBO server to
operate. You will normally not need to modify any global parameter other than
BaseDir, NetPassword and Interfaces. If you are using registry based
configuration, you are asked for the value of the NetPassword parameter during the
initial setup of the REMBO server, and the BaseDir parameter is set automatically.

17
Chapter 2. REMBO Server Configuration
But if you are using the file based configuration, you have to edit the configuration
file to modify these two parameters before starting the server for the first time.
Here is a quick reference for global parameters common to all services (basic
parameters):

BaseDir "string"
Specifies the base directory for the server. All paths included in the configuration
are relative to this base directory. This parameter is a mandatory parameter, and
has no default value (i.e. you must set it before starting the server for the first
time if you are using file-based configuration mode). Read the manual page for
more information.

NetPassword "string"
This is the password used by the REMBO server to protect its files against
illegitimate remote access. If you are using Netclnt, you will have to enter the
same password in the open command to be able to access the server files
remotely. If you are using the server console, you will need to enter a password
only if you have added a server in the remote server mode. If the server is the
local server, or a remote Windows NT server, the console will be able to retrieve
the password from the registry (you will get access to the files without entering a
password). Read the manual page for more information.

MaxLogSize number
This parameter can be used to limit the size of the log file generated by the
REMBO server. The maximal log size must be specified in bytes, and apply to all
the log files created by the server (file,nbp and boot). If you do not specify this
parameter, or set the limit to 0, then log files are not limited in size. Read the
manual page for more information.

Interfaces "string"
This parameter is used to specify the list of network interfaces used by the server
when receiving and sending packets to REMBO clients. If you leave this option
unset, the server will use the network interface corresponding to the official
hostname of the server. Read the manual page for more information.

18
Chapter 2. REMBO Server Configuration

Set the Interfaces parameter if the REMBO server is installed on a


multi-homed host (i.e. a host with multiple network cards).

Other global parameters are used to define advanced parameters, related to the PXE
behaviour of the REMBO server, and REMBO specific parameters.

2.2.1. Parameters related to PXE


The REMBO server implements all the PXE services required by the PXE
specification. PXE configuration parameters let you disable the PXE services not
needed in your specific environment, or change settings to accomodate with an
existing PXE infrastructure.
The PXE specification defines three different ways for a PXE remote-boot client to
find its PXE server (i.e. the REMBO server):

• The DHCP option 60 is set to PXEClient


• If the reply packet sent by the DHCP server to the remote-boot client includes
the DHCP option 60, and the value of this option is set to PXEClient, the
remote-boot client knows that the PXE server is on the same host as the DHCP
server. The PXE negotiation continues by sending a packet on the UDP port 4011
on the server.
If you have choosed this mode of operation, you can use DisableDHCPProxy and
BootNoMulticastDiscovery to disable the DHCPProxy and PXE multicast
discovery PXE services.

• The PXE server sends a PXE reply to the DHCP discover (DHCP Proxy)
• If the DHCP server and the PXE server are not on the same computer, the PXE
server can be configured to reply to DHCP requests (DHCPDISCOVER) sent by
the remote-boot client. The remote-boot client will thus receive two reply packets
for its initial DHCP request: one from the DHCP server (DHCPOFFER), and one
from the PXE server. The reply coming from the DHCP server contains the IP
address and network parameters associated with the remote-boot client, and the
reply from the PXE server contains PXE specific options.
This method only works if the remote-boot client and the REMBO server are on
the same subnet, as the initial DHCP request sent by the remote-boot client is a
local IP broadcast (broadcasts are usually blocked by routers).
If you have choosed this mode of operation, DisableDHCPProxy must not be set
(i.e. DHCPProxy must be activated), and you might want to disable PXE
multicast discovery with BootNoMulticastDiscovery.

19
Chapter 2. REMBO Server Configuration

• The DHCP reply tells the client to perform multicast discovery


• If none of the two above methods can be used, then the DHCP server can be
configured to include PXE parameters for multicast discovery. These parameters
will tell the remote-boot client how to perform the PXE multicast discovery
(which address to use, and which server to search for). The PXE specification
defines which DHCP parameters need to be changed for multicast discovery. The
boot ID for REMBO servers is 15.
If you have choosed this mode of operation, BootNoMulticastDiscovery must
not be set (i.e. PXE multicast discovery must be activated), and
BootDiscoveryAddress must be set to the multicast address used in your
discovery infrastructure. You might want to disable DHCPProxy with
DisableDHCPProxy.

If you have multiple REMBO server on the same subnet, you can implement
load-balancing and fault-tolerance by enabling DHCPProxy on all servers, and
defining the clients in all servers. See (Section 2.2.3 for more information).
Here is a quick reference for PXE parameters:

DisableDHCPProxy
When this parameter is present in the configuration, the DHCPProxy service is
disabled in the REMBO server. The server will not send extended DHCP replies
(PXE replies) to DHCP discover packets sent on the network by remote-boot
client. Read the manual page for more information.

DisableBOOT
When this parameter is present in the configuration, the PXE component of the
REMBO server will be disable, no clients will be able to boot. Read the manual
page for more information.

DisableNBP
When this parameter is present in the configuration, the NBP component of the
REMBO server will stop answering requests coming on the NBP port. Read the
manual page for more information.

20
Chapter 2. REMBO Server Configuration

DisableFILE
When this parameter is present in the configuration, the FILE (NetFS,MCAST)
component of the REMBO server is disable. Read the manual page for more
information.

DisableTCP
When this parameter is present in the configuration, the TCP component of the
REMBO server will be disable. Read the manual page for more information.

BootNoMulticastDiscovery
When this parameter is present in the configuration, the PXE multicast discovery
support is disabled in the REMBO server. This means that the server will not
listen for multicast PXE discovery packets. Read the manual page for more
information.

BootDiscoveryAddress ip-addr
This is the multicast IP address the server listens on when waiting for PXE
multicast discovery packets. Read the manual page for more information.

BootDiscoveryPort port
This is the port the server uses when listening to multicast discovery packets and
BINL requests. Read the manual page for more information.

Another important part of the PXE support implemented in the REMBO server is
the MTFTP (Multicast Trivial Transfer Protocol) service. This protocol is used by
PXE compliant bootroms to download the initial part of the REMBO client side.
Once the initial part of REMBO is downloaded, proprietary protocols are used to
provide a better service level (reliable and secure service).
The MTFTP service implemented in the REMBO server is not a full MTFTP server
as defined in the protocol specification. It was designed to send the initial part of the
REMBO client side, and nothing more. The following parameters allow you to
change the MTFTP settings, although default values work in most cases:

MTFTPPort port

21
Chapter 2. REMBO Server Configuration
This is the port used by the server when listening to MTFTP requests. Read the
manual page for more information.

MTFTPClients port [:client-port ]


This is the destination IP address and port used by the server when sending
multicast MTFTP datagram to clients. Read the manual page for more
information.

MTFTPStartDelay secs
This is the delay used by remote-boot clients before sending the first MTFTP
request to the server. Read the manual page for more information.

MTFTPMCastTTL ttl
This parameter defines the Time-To-Live (TTL) associated with MTFTP
multicast packets sent to remote-boot clients. Read the manual page for more
information.

2.2.2. REMBO specific parameters


The REMBO specific parameters are used to modify the behaviour of the
file-related and NBP services of the REMBO server. You will probably not need to
use these parameters unless you want to change the ports or ip address REMBO
uses because these ports are already used for other services on your network.
Here is a quick-reference of all REMBO specific global parameters:

NBPServerPort port
This is the UDP port used by the REMBO server to receive NBP requests from
REMBO clients. It is safe not to change this value. Read the manual page for
more information.

DataDir "path"
This is the directory where server internal files are stored. Read the manual page
for more information.

22
Chapter 2. REMBO Server Configuration
SharedDir "path"
This is the directory where the server stores the shared repository for shared
archives. Read the manual page for more information.

FileServerPort port
This is the UDP port used by the REMBO server to receive NETfs, MCAST and
FAST requests. Read the manual page for more information.

TCPServerPort "port"
This option defines the TCP port used by the TCP component of the Rembo.
Read the manual page for more information.

MaxPCASTSessions number
This is the maximum number of PCAST sessions that the server will accept
simultaneously. This parameter is mostly relevant if the server is running in
UNICAST mode and deploying a group with UNICAST setting. Read the
manual page for more information.

FileMCASTAddress ip-addr:port
(and FileMCASTAddrCount) This is the destination IP address and destination
port used by the REMBO server when sending multicast datagrams for the
MCAST protocol. Read the manual page for more information.

FileMCASTTTL ttl
This is the Time-To-Live used in multicast datagrams sent by the server to
remote-boot clients when using the MCAST protocol. Read the manual page for
more information.

FileMCASTEncrypt
All the datagrams sent with the MCAST protocol are encrypted if this option is
set. Read the manual page for more information.

FASTEncrypt
All the datagrams sent with the FAST protocol are encrypted if this option is set.
Read the manual page for more information.

23
Chapter 2. REMBO Server Configuration

FASTPort port
This is the port used by the server when remote-boot clients use the FAST
protocol to send files to the server. Read the manual page for more information.

2.2.3. Configuration parameters related to fault-tolerance


A fault-tolerant system is a system which is able to continue to work even when one
of its components fails. In the case of REMBO servers, you configure a server for
not answering to remote-boot client unless the primary server has failed. This will
ensure high availability even when the primary server fails, or when maintenance
that requires the server to be shutdown is performed on the primary server.
Read Section 4.1 for more information.
Here is a quick-reference of fault-tolerance specific parameters:

Backup ipaddr
This parameter defines the IP address of a backup server for this REMBO server.
Read the manual page for more information.

BootReplyDelay secs
This is the number of seconds the server will wait before sending the reply packet
to a multicast discovery packet, a BINL packet or a DHCP discover packet. Read
the manual page for more information.

2.3. Authentication domains


An authentication domain is a group of parameters related to the authentication of
users by REMBO. The term domain has nothing to do with Windows NT domains,
or NIS+ domains. Parameters contained in an authentication domain define how
user and password information entered on a client REMBO workstation is checked
by the server. For example, it could be checked against the local server’s database of
users, or through a remote authentication device (with Radius). Additionally,
REMBO allows to restrict the search for matching users to a single user group (NT
user group, or Unix user group) for greater flexibility.

24
Chapter 2. REMBO Server Configuration
The REMBO server supports several authentication protocols, depending on the
platform the server runs on:

• On Windows NT, a user identity can be verified with the local user database, or a
remote user database (but still on a Windows NT server);
• On Unix, the user identity is verified with the standard user database functions,
which can be configured to use local files, NIS or NIS+. Note that PAM will be
used if the server is running on Linux;
• And on both platforms, the REMBO server can use the authentication standard
Radius to perform the authentication with a device supporting the Radius
protocol, or with a Radius gateway for Netware (NDS) for example.

Under Windows NT, authentication can be done only if the user running the
REMBO server has the Act as part of the Operating System privilege. By
default, the user account used for services has this privilege (SYSTEM account).
If you are using NT remote authentication, the REMBO server must have this
privilege on the remote computer.

If you are using file-based configuration mode, you must add authentication
domains in the configuration file. Each domain starts with AuthLocalDomain,
AuthNTDomain (on Windows NT only), or AuthRadiusDomain, and is followed by
the name you want to attribute to this domain. The domain name can then be used
in host groups to link an authentication domain with a group of hosts (see Section
2.5). Here is an example showing the three forms of authentication domains in a
file-based configuration:

AuthLocalDomain lcltest {
UserGroup "rembo"
}
AuthNTDomain ntatest {
AuthServerName "company-pdc"
UserGroup "rembo"
}
AuthRadiusDomain radtest {
AuthServerAddress 192.168.1.15
RadiusSecret "testing123"
}

If you are using registry-based configuration, you can add a new authentication
domain with the server console by clicking on the Parameters subkey and choosing

25
Chapter 2. REMBO Server Configuration
Add Auth Domain from the Add/Remove menu. A form allowing you to define the
parameters for the domain will appear.
Here is a quick reference for authentication domains:

• Local domains use the local user database to authentify a user. The optional
UserGroup parameter can be used to restrict the verification to a specific group of
users. This type of domain is supported by both NT and Unix versions of the
REMBO server.
• Remote NT domains forward authentication requests to the NT server specified
by the mandatory parameter AuthServerName. The optional UserGroup can be
used to restrict the verification to a specific group of users. This type of domain is
supported by the NT implementation of the REMBO server only.
• Radius domains forward authentication requests to the Radius-compliant device
specified by the parameter AuthServerAddress. The value of the parameter
RadiusSecret is used as the secret for the Radius communication, and must
match the secret stored in the configuration of the Radius device for the protocol
to work.

On the client side of REMBO, you can use authentication domains with the
wizards, or with the AuthUser, AuthUserEx, LogonUser,and Logon Rembo-C
functions.

2.4. TCP tunnels


A TCP tunnel is a way to provide TCP connectivity in REMBO clients. A TCP
tunnel defines a hostname and a port which is made accessible to REMBO clients
through specific Rembo-C clients.
TCP tunnels can be used to provide a wide range of interesting applications on the
client-side. Here are some examples:

• Access to a SMTP server to send mail to an administrator if something wrong


has been detected by REMBO;
• Access to a database server (through an TCP-to-ODBC gateway) to get
information or instructions on what kind of operation to perform, or to store
information about the computer (hardware inventory);
• Access to a HTTP server (web server) to retrieve information directly from the
world-wide-web;
• Access to proprietary management suites, or to interface with specific
authentication methods.

26
Chapter 2. REMBO Server Configuration

If you are using file-based configuration (i.e. rembo.conf), you must add TCP
tunnels in the first part of the configuration file, before the first host group. A TCP
tunnel definition starts with the word TCPTunnel, followed by the tunnel identifier (a
word used by REMBO clients to identify the tunnel). A tunnel definition contains
two mandatory parameters: RemoteHost and RemotePort.
Here is an example of TCP tunnel definition in a file-based configuration. In this
example we define a tunnel called sendmail, connecting REMBO clients to the
company-wide mail server. This tunnel can then be used by the Rembo-C function
SendMail to send mails to network administrators.
TCPTunnel sendmail {
RemoteHost "mail.company.com"
RemotePort 25
}

If you are using registry-based configuration mode, you can use the server console
to create a new tunnel. Simply select "Add Tunnel" in the menu or by clicking with
the right button on the server tree. Enter an identifier (e.g. sendmail), a hostname
(or IP address) and a port.
Here is a quick reference for TCP tunnels:

• RemoteHost is a string representing the TCP remote host to contact when a


REMBO client opens this TCP tunnel. You can either specify a hostname or an IP
address for this parameter. Note that you need to use double quotes (") around the
hostname or IP address if you are using file-based server configuration.
• RemotePort is a number representing the TCP port to connect to when a
REMBO client opens this TCP tunnel. You can get the complete list of valid port
numbers in the file /etc/services on any Unix computer, or in the file
/winnt/system32/drivers/etc/services on a Windows NT computer.

On the client side of REMBO, TCP tunnels are accessed with the following
functions: TCPConnect, TCPRead, TCPWrite and TCPClose.
Rembo-C function SendMail is an example of TCP tunnel usage, as well as
ODBC access functions (see Section 2.8.2 in REMBO Client Administration
Manual).

27
Chapter 2. REMBO Server Configuration
2.5. Host groups
Host groups are used to organize your computers in small units. Each unit (host
group) has its own parameters. A REMBO host group is made of two parts:

• Parameters, such as the HTML page to load on startup, or the authentication


domain to use.
• A list of all the hosts contained in this group. These hosts will use the parameters
defined for this group, or override these parameters with host-specific values.

In most cases, you will only modify the StartPage and Options parameters in a
host group. The former parameter defines which HTML page REMBO shall load on
startup, and the latter is used to switch REMBO from the administrator mode to the
user mode.

2.5.1. The default group


A special group, with the name Default, plays a special role. It does not require a
list of hosts, but is used by the server when a computer connects to the server
without belonging to any group. If there is no default group, the computer is refused
by the server, and it will thus not be able to boot. If there is a default group, the
server accepts the connection and use the parameters defined in the default group
for this computer. You can use this feature to create a secure environment, by
removing the default group from the configuration, and using host lists to assign
authorized hosts to a group. Unauthorized hosts will be refused because they do not
belong to any group, and there is no default group.
If you are using the registry-based configuration mode, you can add a new group
with the server console: click on Parameter, then choose Add Group in the
Add/Remove menu. A dialog box will appear, letting you enter all the parameters for
the new group. None of the parameters are mandatory (i.e. you can leave the fields
blank if you want). You can then add hosts to the new group by choosing the menu
option Add Host in the Add/Remove menu.
In file-based configuration mode, you can add a new group by inserting a Group
statement in the configuration file. Group statements always start with the keyword
Group, followed by the name of the group, followed with the block of parameters
and host lists. The host lists must appear after the last parameter or the server will
not be able to parse the configuration file. See Appendix A for an example of group
statement.
Here is a quick reference of host groups parameters. These parameters must can be
defined at the group level (before the host list in a file-based configuration), or at the
host level (for each Host or HostRange entry).

28
Chapter 2. REMBO Server Configuration

FileServer ipaddr
This parameter can be used to specify the IP address of the host serving the
NETfs, FAST and MCAST protocols. Read the manual page for more
information.

FileServer ipaddr
This parameter can be used to specify the IP address of the host serving the
NETfs, FAST and MCAST protocols. Read the manual page for more
information.

RemoteConsole ipaddr:port
This parameter defines the IP address and port for the Remote Console
application, and instructs REMBO to contact the Remote Console at next boot.
Read the manual page for more information.

Options [admin] [, autoboot] [, novesa] [, noudma] [, nocache] [,


unicast]
Four options can be passed to the hosts contained in the group. These options
define the operation mode of REMBO. Read the manual page for more
information.

PXEBootMode { normal | hdboot | ignore}


Three options can be passed to the hosts contained in the group. These options
define the operation mode of REMBO. Read the manual page for more
information.

Lockout [none] [, poweroff] [, reset] [, mouse] [, keys] [,


screen] [, all]
You can use this parameter to lock a specific peripheral during the time REMBO
is active on the remote-boot client. Read the manual page for more information.

AuthDomain "domain"
This is the authentication domain to use when one of the hosts of the group needs
to check the identity of a user. Read the manual page for more information.

29
Chapter 2. REMBO Server Configuration

StartPage "path"
This parameter defines the HTML to load when REMBO starts on the
remote-boot client. Read the manual page for more information.

Host ip-addr
Host hw-addr
This is a host entry in the host list for the group. Read the manual page for more
information.

HostRange startip -> endip


This is an entry for a range of hosts. Read the manual page for more information.

30
Chapter 3. Rembo Server Management Tools

Two tools are provided for managing your REMBO server: NetClnt, a
command-line utility for accessing server files, and the Server Console, a Windows
Application for managing all the aspects of a Windows NT REMBO server.

3.1. Netclnt
NetClnt is a command-line utility, available for Windows, Linux and Solaris. You
can use NetClnt to access the files stored on a REMBO server remotely, as well as
to perform some maintenance tasks.
Here is a list of features included in NetClnt:

• Communications between NetClnt and the server are protected with a password
and encrypted;
• NetClnt can be used in interactive mode (with an interface similar to a FTP
client), or in batch mode;
• Files can be deleted, renamed, moved, downloaded and uploaded. Directories
can be deleted, renamed and moved;
• Files are downloaded with the NETfs protocol, and uploaded with the FAST
protocol. Special mechanisms are used to optimize file access if NetClnt is used
locally on the server.
• Shared files can be extracted from the server repository, and uploaded to the
server repository. Archives that include both regular files and related shared files
can be created and reimported to the server.

3.1.1. Using NetClnt interactively


Simply execute the file netclnt in the misc directory of your REMBO installation
directory. You will see the interactive prompt NETFS>. You can enter NetClnt
commands interactively, but the first thing to do is to open a connection with a
REMBO server.

3.1.1.1. First step: connecting to a REMBO server


To open a connection with a REMBO server, use the open command, followed with
the IP address (or hostname) of the server. You will be asked for a password. Enter
the same password as the one set in the NetPassword parameter of the remote server.
Using the open command will not generate any network traffic; it will just set
connection parameters in NetClnt.

31
Chapter 3. Rembo Server Management Tools
3.1.1.2. Second step: testing the connection
You can test that you have entered the proper password by issuing a dir command.
This command will download and display the content of the current directory on the
remote server. If this command works (i.e. you see some output), then your
connection is working. Otherwise, double-check the IP address and password you
have entered with the open command.

3.1.1.3. Third step: playing with the connection


You can now use any NetClnt command. You can for example send a new file to the
server (put), change the current directory (cd) or get a server file locally (get). Note
that when you want to send a file to the server, the file must exist on your local
computer, in the current directory (you can change the current local directory with
lcd). And also note that downloaded files are stored in the current local directory.
See the reference below for more information on commands. At any time, you may
use the command help to get the list of valid commands, and time a command
name without argument to get a short summary of its syntax.

3.1.2. Using NetClnt in batch mode


You can use the batch mode of NetClnt to create scripts operating on remote files
without any user intervention (e.g. files upgrade).
To use NetClnt in batch mode, create a text file containing the sequence of
commands you want to execute with NetClnt, and run netclnt filename where
filename is the name of the text file containing the sequence of commands. The
first command must be the open command, with a valid IP address and a valid
password (password can be passed as the third parameter to open).
New in build 2.0.044: parameters can be passed to your netclnt script, and can be
used in the script with the # prefix. For example, every occurence of #1 in your
script will be replaced with the first following the script name in the command-line
used to run netclnt. To use this new feature, netclnt must be called with the
following syntax: netclnt -f scriptname parameters where scriptname is the
filename of the netclnt script to execute, and parameters are the parameters passed
to the netclnt script. The new command chkparams can be used to check that the
number of parameters passed to the script corresponds to what the script is
expecting.

3.1.2.1. Batch mode example


Here is an example of batch file for use with NetClnt:
open 192.168.1.10 rembopwd
lock
mkdir /myfiles

32
Chapter 3. Rembo Server Management Tools
cd /myfiles
put file1
put file2
put file3
exit

Here is an example with parameters. This example would be run with netclnt -f
script 192.168.1.10 rembopwd
chkparams 2 <server-ip> <rembo-password>
open #1 #2
dir
exit

3.1.3. Using NetClnt to manage the shared repository


With the introduction of the new shared repository (for storing a unique copy of
each file in the disk images), some new command have been added to NetClnt to
help you manage its content.

3.1.3.1. Creating a duplicate repository


The commands getshared and putshared can be used to download and upload all
shared files related to a given archive, to and from a local shared repository. This
can be used to duplicate a part of the server shared repository locally, for backup
purposes or to transfer it to another server.
Note that the local shared repository uses the client format of index files (the same
as used by REMBO client), which is slightly different from the server format (the
server format is ready to handle a large number of simultaneous clients, while the
local format is optimized for local access only). Therefore, you should not copy a
shared repository built using getshared directly onto a server, but use the
putshared instead.

3.1.3.2. Exporting shared files


A more convenient way to manipulate disk archives along with the related shared
files is to use .rad file exports. A .rad file can embbed several archive headers and
other files, as well as all related shared files. It is a convenient way to backup and
transmit archives in a self-contained format. See the description of the commands
radget, radput and radglist below.

33
Chapter 3. Rembo Server Management Tools
3.1.3.3. Synchronizing shared repositories
When using several REMBO servers, if archive files are copied manually or using a
replication mechanism from one server to the other, it may be required to
synchronize the shared repositories to ensure that the destination server has all
necessary server files. The sync, msync and rsync commands can do that on a
specified subset of server files. These commands will ask the targeted server to
directly contact the master server and download any missing shared file. See the
documentation for these commands below, as well as Section 4.1.3. Combined with
the command xcopy, rsync is the best solution to replicate the content of a master
Rembo server on a slave Rembo server.

3.1.4. NetClnt command reference


Here is the complete reference for NetClnt commands:

open host [password]


connect host [password]
This is the first command to issue when starting NetClnt. This command will
setup the connection information required for remote access to the REMBO
server. If you do not specify the password in the command line, you will be asked
to enter the password interactively.

close
Close the current connection. This command must be issued if you want to issue
a new connect command to the same server, but with a different password.

pwd
Display the current remote directory.

dir [path ]
ls [path ]
Display the content of a directory on the remote server. If you use dir without
parameters, the current directory on the server will be displayed (you can use cd
to change the current remote directory). If you use a parameter, the content of the
directory specified by the parameter will be displayed (the path is relative to the
current remote directory).

34
Chapter 3. Rembo Server Management Tools

cd path
chdir path
Change the current remote directory. When NetClnt starts, the current remote
directory is the root of the server filesystem. The path is relative to the current
remote directory.

md path
mkdir path
Create a new directory on the server. The path is relative to the current remote
directory.

rd path
rmdir path
Delete a directory on the server. The directory must be empty. The path is relative
to the current remote directory.

deltree path
Delete a remote directory and all its sub-directories. The target directory does not
require to be empty. Use this command with caution.

ren old-name new-name


move old-name new-name
Rename or move a file on the server. Both the old filename and the new filename
must be specified. If the new filename is in a different directory than the old
filename, the file is moved. Paths are relative to the current remote directory.

del path
rm path
Remove (delete) a file on the server. The path is relative to the current remote
directory. If the path is a globbing pattern, all matching files are deleted.
Acceptable globbing wildcards are the asterisk and the question mark.

lcd path

35
Chapter 3. Rembo Server Management Tools
Change the current directory on the local computer. This command has no effect
on the server: it only modifies the current directory on the computer which runs
NetClnt.

!localcommand
Execute a command on the local computer. For example, !dir displays the
content of the current directory on the local computer. !edit myfile starts the
MS-DOS editor on the file myfile.

get remote-path [local-path]


mget pattern
rget pattern
Download the remote file remote-path from the current remote directory into the
file local-path in the current local directory. If the second parameter is
ommitted, the file is stored under the name remote-path. The mget variant
downloads all remote files that match the globbing pattern to the local
directory. Acceptable globbing wildcards are the asterisk and the question mark.
The rget variant recursively enter into all directories that match the globbing
pattern (all files within the directory entered will be copied).

put local-path [remote-path]


mput pattern
rput pattern
Upload the local file local-path from the local remote directory into the file
remote-path in the current remote directory. If the second parameter is
ommitted, the file is stored under the name local-path on the server. The mput
variant uploads all local files that match the globbing pattern to the remote
directory. Acceptable globbing wildcards are the asterisk and the question mark.
The rput variant recursively enter into all directories that match the globbing
pattern (all files within the directory entered will be copied).

xcopy [-d remote-server remote-source-dir local-dest-dir


]
Copy files recursively, from a remote server to a local server. All the files stored
in the directory remote-source-dir on the remote server
remote-server are copied in the directory local-dest-dir on the local
server. Tests are made on the source and the destination to skip files that have
already been copied. This function can therefore be used to synchronize two

36
Chapter 3. Rembo Server Management Tools
servers on a daily basis, because it will only copy files that have been modified,
or added since the last xcopy operation. By default, xcopy does not delete any file
on the local server. But if -d is specified as the first parameter, xcopy will then
delete every local file that has not been found on the remote server, thus creating
an exact copy of the remote server directory in the local directory. Note that the
server password must be the same on both servers for this command to succeed,
because xcopy uses the password provided to the connect when connecting to the
remote server.

sync master [remote-path]


msync master pattern
rsync master pattern
Order the connected server to download all missing shared files for the archive
specified by remote-path from another REMBO server specified in master. The
server can be specified by its IP address or by its DNS name. The msync variant
trigger the transfer of shared files for all archives that match the globbing
pattern in the remote directory. Acceptable globbing wildcards are the
asterisk and the question mark. The rsync variant recursively enter into all
directories that match the globbing pattern (all files within the directory
entered will be processed). A typical use for replicating all shared files from a
given server is rsync master *. Note that the rsync command involves no file
transfer to and from NetClnt, but only between the two servers.

getshared localarchive [localrepository]


putshared remotearchive [localrepository]
The getshared command downloads all available shared files related to a given
local archive to a local repository. By default, the repository will be created in the
client current working directory, but the path can be overriden by specifying a
localrepository parameter. The localarchive may have been previously
downloaded from the server, or copied by another mean. The putshared
command performs the reverse operation, i.e., uploads all locally available shared
files related to a given server archive to the server shared repository. By default,
files are read from a repository in the client current working directory, but the
path can be overriden by specifying a localrepository parameter. The
remotearchive may have been previously uploaded to the server, or copied by
another mean. Note that both commands optimize network traffic, in the sense
that they will only transfer files that are needed by the specified archive and that
are not already in the destination shared repository.

radget radfile [file*]

37
Chapter 3. Rembo Server Management Tools
radput radfile [file*]
radlist radfile
radcheck radfile
The radget command downloads all files specified on the command line (several
filenames and globbing patterns are accepted), as well as all related shared files.
The result is stored in a monolithic .rad export file, specified in radfile. Note
that a significant amount of disk space may be needed on the client to perform
this operation. The destination file will always be overwritten (files are not added
to an existing radfile). You can use radlist to list the content of a radfile export,
radcheck to verify the internal consistency of a radfile export, and radput to
reupload the files to the same or another server. If no file pattern is specified to
the radput command, then all files in radfile will be uploaded (including all
shared files that are not yet known to the destination server). If a list of files or
patterns is provided, only the matching files will be uploaded. The radput works
very well even if the source radfile is on a network share, as it will only read
the shared file that are not yet present on the destination shared repository.

wake hardware-address
Sends a wake packet to the specified hardware address. This command can be
used to wake (i.e. remote power-on) computers. The target computer must be
located on the same network as the computer running netclnt. Additionnally, the
target computer must be equipped with a wake-on-lan capable network card. The
hardware address must be entered without any delimited. For example, hardware
address 00:10:4B:12:34:56 must be entered as 00104B123456.

sleep sleeptime
Waits sleeptime seconds. This command is useful when used in batch scripts.
No command is executed during the waiting time.

lock
Acquire a unique lock on the computer, that will be automatically released when
NetClnt exits. This mechanism can be used to ensure that there will be only one
instance of NetClnt running at a time on a client, to avoid conflicts on the server,
when automated batch are run automatically.

getlock lockname
releaselock lockname

38
Chapter 3. Rembo Server Management Tools
Acquire or release a server lock. A server lock is identified by a name
(lockname) and can only be locked by one computer at a time. These two
commands can be used to make sure that no computers are accessing a particular
resource during an update. See GetLock in Section 3.11 in Rembo-C Scripting
Reference Manual.

start servername
stop servername
reload servername
Controls the Rembo Windows service on a remote computer (implemented in
Windows netclnt executable only). These commands start, stop or reload the
Rembo server on a remote computer, by using standard Windows remote service
control. The user logged in when running netclnt must have administrator
equivalence on the remote server.

timestamp message
Displays a timestamp and a message to the output. This command can be used in
batch scripts to output the current time on the screen, or in a log file.

chkparams reqparamcount [usage]


Checks the number of parameters and display a usage string if parameters are
missing. This command can only be used in scripts called with the netclnt -f
scriptname params syntax. Chkparam verifies that there is at least
reqparamcount parameters in the command-line, and display a usage string
containing the message in the usage parameter if the number of actual
parameters is less than the requested parameters count.

sqlinit dbgw-ip-addr odbcsource [username password]


sqlclose
sqlexec sql-query
sqlcopy source-dbgw-ip source-odbcsource table-name
[source-username source-password]
This group of functions connect netclnt with a Rembo Auto-Deploy database
gateway (dbgw) to perform SQL queries remotely. The remote host must be
running both dbgw and a Rembo (Auto-Deploy) server. Use SqlInit to initiate
the connection with the remote database gateway. You must provide the name of
the ODBC source to use on the remote host, and the ODBC username and
password if needed. Then, use SqlExec to execute SQL statements on the remote

39
Chapter 3. Rembo Server Management Tools
host, or SqlCopy to copy the content of a table from a given database gateway, to
the remote host (or local host if sqlinit was called to connect to localhost).
When calling SqlCopy, the parameters source-dbgw-ip,
source-dobcsource, source-username and source-password are
used to identify the ODBC source to use as the source of the copy operation,
while table-name is the name of the database table to copy. Calling SqlCopy
on a database table is equivalent to the execution of a select statement on the
source, and delete + insert statements on the destination.

3.2. Server Console


This section gives the instructions on the use the REMBO Server Management
Console application, available for Windows NT.

3.2.1. Introduction
SConsole is a powerful management application for your Rembo servers. It can be
used to

• control the server’s operating status


• start, stop and reload the server
• modify configuration parameters remotely
• create host entries and group entries
• load files from and to the server’s filesystem
• browse the server’s log files
• edit persistent variables

All these operations can be performed on a local Rembo server (i.e. the server
running on the same computer as the console), or on remote servers (servers
connected via Windows NT networking).
By default, the console tries to fetch information about the local server by searching
the local registry. If it finds a local server, this server will be automatically displayed
in the left part of the main window.
If you want to later add other servers, follow the instructions found in Section 3.2.3.

The server console must be run as a local Administrator, or as a user with


enough privileges to access the registry in read/write mode.

40
Chapter 3. Rembo Server Management Tools
3.2.2. The Interface
The interface of the Rembo Console is similar to the File Explorer. On the left you
can see servers and configuration topics (parameters, logs, files, ...) and on the right
you see the elements active in the topic select in the left panel.
Each level of the hierarchy has its own elements, and its own actions. You can use
the right button to show a contextual menu based on your current location in the
hierarchy.
Figure 3-1. The Server Console interface

3.2.3. Adding a server


To add a new server to the list of servers (in the left part of the main window),
choose Add server from the Add/Remove menu or click with the right mouse button
on the Rembo servers icon at the top of the list shown in the left panel: {bmct
bmp/rembo.bmp}.
SConsole supports three different server types, local server, remote NT server or
remote non-NT server. The following descriptions should help you to choose which
type you need for connecting to your Rembo server.
Once added, a new icon representing the server will be displayed in the left part of
the main window. You can manage this new server by clicking on this new icon, and
browsing the parameters, files, logs and configuration parameters of the server.

3.2.3.1. Local Server


Use this type when the server and the console are running on the same computer.
The console will look in the local NT registry to find and edit server’s parameters.
By default, an icon for the local server is added when SConsole starts if a local
server has been detected.

3.2.3.2. Remote NT Server


Use this type to connect to a remote Rembo server (i.e. not running on the same
computer as your console). The console will use Windows NT networking features
to open the system registry on the remote host. That means that you must have
enough privileges to open and write to the registry on the remote computer.

41
Chapter 3. Rembo Server Management Tools
To add the remote server, enter its network name in the add server dialog box.

3.2.3.3. Non-NT Remote Server


If the Rembo server is running under Linux or Solaris, then you must use this type
of server to access the server’s files. Only a limited subset of features will be
activated, because the Console cannot read or write the configuration of a
Linux/Solaris server remotely. Activated features are: files browsing and server logs.
When adding the non-NT server, you will be prompted for a hostname and a
password. The password must be the same as the NetPassword parameter in the
server’s configuration file.
If you choose to let the console remember the server’s password, be aware that the
console will store the password in plain-text in the local computer’s registry.

3.2.4. Server Status


You can see the current status of a Rembo server by clicking on the status icon
under the server’s icon in the left panel.
Figure 3-2. The server status

The first line in the right panel displays the current status of the server. It can be one
of these values:

• RUNNING: The Server is operational and running


• STOPPED: The Server is not running
• START_PENDING: The Server is trying to start
• STOP_PENDING: The Server is trying to stop

If the status is START_PENDING for a long time (it does not change to
RUNNING), it means that the server could not start due to a configuration error or a
runtime error.

You can run the Server from the command-line prompt with the options -d -v 4
to display all the messages generated by the Server during the startup
process. This can help you find the cause of the problem.

42
Chapter 3. Rembo Server Management Tools
3.2.5. Starting the server
If the server status is STOPPED, you can start the Rembo Server by either
right-clicking on the STOPPED status line in the right panel and choosing Start
Server, or choosing Start Server from the Server menu.
The status of the server should change to START_PENDING, then RUNNING.

3.2.6. Stopping the server


If the server status is RUNNING, you can stop the Rembo Server by either
right-clicking on the RUNNING status line in the right panel and choosing Stop
Server, or choosing Stop Server from the Server menu.
The status of the server should change to START_PENDING, then RUNNING.

3.2.7. Reloading the server configuration


You can tell the server to reload its configuration by right-clicking on the status line
in the right panel and choosing Restart server or choosing Restart server in the
Server menu.
This command will fail if the server is not in the RUNNING state.
The server will reload all its groups and hosts configuration, but not the basic and
advanced parameters. If you change a basic or advanced parameter, you must
explicitely stop, then start the server for the changes to be effective.

3.2.8. Modifying parameters


You can use the server console to modify global parameters, authentication domains
or group parameters. For a complete description of the parameters, see Chapter 2.
Parameters are accessible only if the server is a Local Server, or a Remote NT
server. You can access all parameters from the Parameters icon:

• Basic parameters are directly accessible at the Parameters section of the


browsing tree;
• Advanced global parameters are found under the Parameters\Advanced section
of the browsing tree;
• Authentication domains are found under the Parameters\AuthDomains section;
• Host groups are found under the Parameters\Groups section.

You can change any parameter by clicking on its name with the right mouse button
on the right window, and select Modify in the contextual menu.

43
Chapter 3. Rembo Server Management Tools
If a parameter is unset, the icon on the left of the parameter’s name appears greyed,
and the default value is displayed.

3.2.9. Modifying variables


You can add, modify and delete persistent variables from the server console.
Persistent variables are defined in Section 2.2 in REMBO Client Administration
Manual.

Persistent variable access is limited to the local server and remote NT servers.
A persistent variable can be global, local to a group, or local to a host. Global
variables are found under the Parameters\Variables section of the browsing tree.
The right window shows the list of variables already defined. To add a new variable,
click with the right button in the right window, and select New integer variable,
New string variable, or New boolean variable in the contextual menu. You can
modify a variable by right-clicking on its name in the right window and selecting
Modify in the contextual menu. To delete a variable, click with the right button on
its name and choose Delete in the contextual menu.
To access the variables defined for a specific group of hosts, click on the Variables
icon under the group icon you want to modify in the browsing tree. You can then
use the variables as described for global variables (see above paragraph).
Host specific variables are accessible with the Variables icon under the host icon
for the host entry you want to modify.

3.2.10. Browsing the log files


The Console allows you to access the log files created by the server during
execution. These logs contain useful information when you suspect that something
is going wrong.
Figure 3-3. Browsing the log files

The verbosity of the messages generated by the server directly depends on the
GlobalDebugLevel advanced parameter.
Three log files can be inspected with the Console:

• The Boot log, which contains informations about the PXE Proxy service, the
PXE Boot Discovery service and the MTFTP service.

44
Chapter 3. Rembo Server Management Tools
• The NBP log, which contains informations about the group/host parameters, the
authentication requests and the NT domain join requets.
• The File log, which contains informations about all multicast and unicast file
transfers between Rembo itself and the server.

To browse a log file, double click on the file name in the right panel. The content of
the file is displayed by Rembo Quick Editor. Log files are read-only.

3.2.11. Accessing the server files


The file system explorer of the Console works like the Windows File Explorer: you
can drag and drop files and directories from/to the right panel to other windows
applications.
Figure 3-4. Browsing the server files

Essential commands (delete, copy, paste,makedir) are available in a contextual


menu when you click with the right mouse button on an object in the right panel.
You can edit an text file with Rembo Quick Edit by double clicking on the file icon
in the right panel.
You can refresh the right panel with the F5 key.

3.2.12. Frequently asked questions

• Q: I have just saved my file with Rembo Quick Editor and the Console still
reports a size of 0.
• A: Press F5 to refresh
• Q: I cannot drag and drop from the Console to Explorer...
• A: Some versions of Windows NT seem to have problems with drag and drop.
Use download in the file menu instead.
• Q: Where is the SaveAs function in Quick Edit ?
• A: There is no SaveAs function. Copy the file with copy/paste before starting the
editor.

45
Chapter 4. Rembo Enterprise Deployment

This chapter describes features needed in large corporations or institutions


(enterprise features). Fault-tolerance adds robustness to your remote-boot
infrastructure, while file distribution is the ideal way to distribute hard disk images
to multiple REMBO servers. Please note that the file distribution module is only
available in the Enterprise edition of REMBO

4.1. Fault tolerance


A system is fault-tolerant if it is able to continue to perform when one of its parts
fails. In the case of REMBO servers, the whole system is fault-tolerant if REMBO
servers are backuping each others. When a server fails, other servers handle the
requests for the down server.
Note that implementing fault-tolerance at the REMBO level does not mean that
your whole network infrastructure will be fault-tolerant. You are encouraged to
implement fault-tolerances at all levels:

• At the physical level, by having redundant power sources (if all REMBO servers
are out of power at the same time, fault-tolerance at the REMBO level is useless);
• At the network level, by having backup network links, and backup active
elements (the backup server must be able to reach remote-boot clients);
• At the network operating system level, by having multiple network domains, or
by running REMBO servers outside of your domain architecture (i.e. REMBO
server should not be all linked to the same NT PDC, or the same NFS server);
• At the DHCP level, by having multiple DHCP servers on the same subnet;
• At the REMBO level, by implementing the fault-tolerance instructions found in
this chapter;
• Finally, at the operating system level. If REMBO is able to survive to a severe
problem, but then the operating system cannot find its network server,
fault-tolerance is useless.

We will discuss how to implement fault-tolerance at the DHCP and REMBO levels.
Other levels are out of the scope of this document.

4.1.1. Fault-tolerance at the DHCP level


The DHCP protocol has been designed in a way that allows to implement
fault-tolerance and load-balancing very easily. If two DHCP server are connected to

46
Chapter 4. Rembo Enterprise Deployment
the same IP subnet, and both servers are configured to serve IP addresses on this
subnet, the protocol will handle all conflicts between the two servers.
When a remote-boot client requests an IP address, the request packet is sent to the
local broadcast address, that is, to all hosts connected to the same IP subnet as the
remote-boot client. If one or more DHCP servers are connected to the subnet, they
will send a DHCP offer packet to the remote-boot client, containing an IP address
allocated in the server pool of address, or administratively assigned to the
remote-boot client (in case of statical binding between the hardware address and an
IP address in the DHCP configuration, also called a reservation). If more than one
DHCP offer packet is received by the remote-boot client, only the most informative
offer will be kept by the client. By "informative", we mean an offer with enough
PXE information to go further in the PXE discovery.
When the remote-boot client has selected a valid offer, it replies to the server from
where the offer originated with a broadcast packet. This packet is received by all the
hosts connected to the local subnet, including the DHCP servers. This packet is
used by DHCP servers to know if their offer has been accepted or refused by the
remote-boot client. If the offer has been accepted, the IP address is locked in the
DHCP server database, and the DHCP process can continue in unicast mode
between the remote-boot client and the DHCP server. If the reply is for another
offer, the server will release the IP address for his offer (which has been ignored by
the client), and will lock the IP address seen in the offer reply, to mark the IP
address as used on this local subnet (even if the IP address has been allocated by
another DHCP server).
You can therefore implement fault-tolerance by configuring multiple DHCP server
for the same subnet. If the DHCP servers are identically configured, then the
remote-boot clients will always select the first offer, that is, the offer coming from
the fastest server. This can be used to implement load-balancing at the same time as
fault-tolerance: the fastest server is always selected, and if the fastest server
becomes overloaded, another server will be able to send its offer first, and will
become the fastest server.

4.1.2. Fault-tolerance at the REMBO level


Fault-tolerance at the REMBO level is implemented with two configuration
parameters: Backup and BootReplyDelay.
To understand how fault-tolerance is implemented at the REMBO level, you must
remember that the boot process is made of several phases: DHCP discovery, PXE
discovery, MTFTP download and finally REMBO. Fault-tolerance at the DHCP
level is described in the previous section. Fault-tolerance at the PXE discovery level
can be achieved by using multiple REMBO servers in Proxy DHCP mode (i.e. there
is no REMBO server on the DHCP server host, but all REMBO servers are
connected to the subnet). In Proxy DHCP mode, REMBO servers will send PXE

47
Chapter 4. Rembo Enterprise Deployment
reply packets to DHCP discovery packet initially sent by the remote-boot client.
Since DHCP discovery packets are sent to the broadcast address, all REMBO
servers will receive the discovery, and all will send a reply packet, with the
following considerations:

• The remote-boot client must be known by the server (either by being a member
of a host group in the server’s configuration, or if the configuration contains a
default group);
• The server will not answer immediately if the parameter BootReplyDelay is set.

You can use BootReplyDelay to introduce a preference order between the REMBO
servers on a same subnet. The server with the lowest BootReplyDelay (or with no
BootReplyDelay parameter set) will be the first to answer DHCP discovery packets.
All remote-boot clients will be redirected to this server. But if this server fails, the
server with the second lowest value for BootReplyDelay will be the first one to
answer, and so on. Fault-tolerance at the PXE discovery level is in place.
If several REMBO (or all) have the same value for the BootReplyDelay parameter,
they will all send the PXE reply at the same time, and the remote-boot client will
select the first one, or the fastest server. This specific environment can be used to
implement load-balancing at the REMBO level.
Once the remote-boot client has selected its DHCP and PXE server, the REMBO
bootstrap can be downloaded from the PXE server (REMBO server), and REMBO
client-side is started. You can implement fault-tolerance inside REMBO by using
the Backup parameter for specifying a backup server. This value will be sent to the
remote-boot client during the initial startup of the REMBO client, and will be used
as a backup server if the primary server fails. The internal network protocols used in
REMBO have been designed to allow the client to switch from the primary to the
backup server in the middle of a file transfer. However, this only works under the
following considerations:

• Files opened in write mode (upload to the server) cannot be switched to a backup
server. This would cause data corruption on the server, because one part of the file
would be written on the primary server, and the other part on the backup server;
• The filesystem structure on the primary and backup servers must be strictly
identical (i.e. the same content under the files directory of the server).

We suggest using backup servers at the REMBO level (with the Backup parameter)
when you have stabilized your system (hard-disk images are built, scripts are
ready). Once everything is stabilized on primary server, copy the files directory
from primary to backup server, and set the Backup parameter on primary server.

48
Chapter 4. Rembo Enterprise Deployment
4.1.3. Synchronizing multiple REMBO servers
Synchronizing the files and the shared repository of two or more REMBO server
may be required when running REMBO in a high-availability environment. If one
server stops serving clients, another server can be substituted to the failing server
with very low or no downtime, because both servers have the same files available to
clients. Replication is also desirable in environments where Rembo is used on
multiple sites, where every Rembo server has to be synchronized with one single,
master server.
We will assume that one REMBO server is considered as the master server, where
the administrator modifies and updates files, while other servers are considered
slaves, or read-only. Synchronizing servers corresponds to updating files on slaves
using up-to-date information from the master.
Note that the instructions provided here are based on Toolkit version 2.0.044 or
later.
Three different options are available to synchronize a master server with one or
more slave servers:

1. Full copy of all server files and of the shared repository;


2. Optimal copy of all server files, followed by an optimal synchronization of the
shared repository;
3. Selective transfer of server files, including an optimal importation of the
required shared files;

If you are upgrading a REMBO 1.x configuration but have not used the
conversion procedure to use the new native filesystem (see Section 2.2.3 in
REMBO concepts and upgrade procedure), only the third method is available.
It is highly recommended to run the conversion procedure and run the server
in the new native mode.
The new native server filesystem is ideal for server replication, because the server
now always checks the timestamp of every directory in which it searches for files,
and automatically adds new files into the lists of inodes visible the client. Thanks to
this, any file added or changed by a third-party replication software will
automatically be visible to the slave server, without the need to restart the server.
Similarly, when a server is only reading from its shared repository but not writing to
it, it will automatically detect any update to the index files made by a third-party
replication software and reload them when needed.

49
Chapter 4. Rembo Enterprise Deployment
4.1.3.1. Replicating the whole server filesystem blindly
The easiest way to replicate a master server to a slave server is to copy all files that
have changed from the master to the client, using the rsync command
(recommended), Windows Resource Kit’s robocopy, or a similar tool. The
advantage of using a more explicit synchronization system (like rsync) is that you
can better control the time at which the synchronization occurs.
To ensure a proper replication, the slave server should run with read-only
permissions, so that the replication system always has free access to update the files.
The slave server will automatically detect when a file has been changed, and update
its state accordingly.
Note that this may not be the most efficient replication mechanism over slow links
since some repository files may have to be sent completely, while only some parts
may have changed. Since each repository block is 128MB in size, small changes
can result in very high bandwidth usage. In addition, it is only applicable when the
slave server is a strict copy of the master, and when all new files come from the
master (the slave is read-only).

4.1.3.2. Server repository synchronization


Another relatively easy alternative to server replication, that gives more flexibility,
is to replicate the visible files using the xcopy command in netclnt, and then ask the
slave server to do a smart synchronization of its shared files with the master server.
Since xcopy only transfers files that need to be copied, bandwidth usage is limited.
In order to do this, you should select which directories you want to replicate with
xcopy, and create a netclnt batch script for the replication. In this case, the slave
filesystem does not need to be read-only.
Use a (possibly scheduled) netclnt script to execute the xcopy commands and ask
the slave server to scan its archives and query missing shared files from the master
(see Section 3.1.3.3). This synchronization will be optimal, and will only transfer
the minimal amount of data (using a TCP protocol). Note that the slave repository
will then evolve on its own, and although all files used by files replicated from the
master will be present in the slave shared repository, the shared repository files may
differ.
Example of a netclnt synchronization script:
This example would be called as follows:
netclnt -f sync.nc 192.168.1.5 netpwd >> sync.log

With this content for sync.nc:

chkparams 2 server-ip server-password


open localhost #2
timestamp Starting file synchronization
xcopy #1 /hdimages /hdimages

50
Chapter 4. Rembo Enterprise Deployment
xcopy #1 /floppy /floppy
#... add xcopy commands as needed
timestamp Starting shared repository sync
rsync #2 *
timestamp Synchronization done
exit

4.1.3.3. Selective transfer of server files


If you need even more control on the transfer of server files (for instance if two
different administrators are managing the master and slave servers, and the
extraction of files from the master should not be bound to the importation into the
slave server), you may use the .rad file exports and imports, as described in Section
3.1.3.2.
The principle is very simple: the administrator in charge of the master server create
a .rad export of the files to distribute, that will include all related shared files. The
export file is then put on a network share, accessible to the slave server
administrator. When the import is desirable on the slave server, the administrator
launches the command, directly from the network share. The import function will
only read the minimal portions of the file needed to reimport the selected files, using
a synchronization mechanism similar to the one described in the previous
subsection.
Note that if you prefer to work with a GUI tool under Windows, you may use the
SConsole to do the export/import operations.

51
I. Global parameters reference
Table of Contents
Backup .................................................................................................................... 54
BaseDir.................................................................................................................... 55
BootDiscoveryAddress........................................................................................... 56
BootDiscoveryPort ................................................................................................. 57
BootNoMulticastDiscovery.................................................................................... 58
BootReplyDelay...................................................................................................... 59
DataDir.................................................................................................................... 60
SharedDir................................................................................................................ 61
DisableDHCPProxy ............................................................................................... 62
DisableBOOT ......................................................................................................... 63
DisableNBP............................................................................................................. 64
DisableFILE ........................................................................................................... 65
DisableTCP............................................................................................................. 66
FASTEncrypt.......................................................................................................... 67
FASTPort ................................................................................................................ 68
MaxPCASTSessions............................................................................................... 69
FileMCASTAddress ............................................................................................... 70
FileMCASTEncrypt............................................................................................... 71
FileMCASTTTL..................................................................................................... 72
FileServerPort ........................................................................................................ 73
TCPServerPort....................................................................................................... 74
Interfaces ................................................................................................................ 75
MaxLogSize ............................................................................................................ 76
MTFTPClients........................................................................................................ 77
MTFTPMCastTTL ................................................................................................ 78
MTFTPPort ............................................................................................................ 79
MTFTPStartDelay ................................................................................................. 80
NBPServerPort....................................................................................................... 81
NetPassword ........................................................................................................... 82
Global parameters reference
Backup
Backup — IP address of backup server
Synopsis

Backup ip-addr

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
This parameter defines the IP address of a backup server for this REMBO server.
The backup server IP address is sent to all remote-boot clients connected to this
server. If this server fails, the remote-boot clients will detect that the primary server
has failed, and will automatically switch to the backup server.
Here are some considerations about the REMBO server running at the IP address
specified by this parameter (the backup):

• The backup must be configured to use the same UDP ports as this server for the
NBP, FILE, MCAST and FAST services (i.e. for all REMBO specific services);
• Its filesystem must be strictlyidentical to the filesystem of this server, so that
remote-boot clients can switch from one server to the other in the middle of a file
transfer;
• Ideally, the backup should be configured to answer DHCP discovers and PXE
discovers for the same clients as this server, but with a higher delay (see
BootReplyDelay). This will ensure that the remote-client will boot on the backup
server on the next boot.

See Section 4.1 for more information about fault-tolerance.

Example
Backup 192.168.1.4

54
BaseDir
BaseDir — Directory for all server files
Synopsis

BaseDir "directory"

Location in the configuration

• Registry-based:\Parameters
• File-based:Beginning of the file

Description
This parameter is used by the server as a prefix for all data files, including the log
files and the filesystem files.
You must set this parameter to the directory where you have installed the REMBO
server executable. If you are using the Windows NT version of REMBO, the
BaseDir parameter is automatically configured during the setup process.

Always use forward slashes (/) in all path names you enter in the text-based
configuration file.

Examples
BaseDir "c:/Program Files/Rembo Server"
BaseDir "/usr/local/rembo"

55
BootDiscoveryAddress
BootDiscoveryAddress — Multicast address used for PXE discovery
requests
Synopsis

BootDiscoveryAddress ip-addr

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
If PXE multicast boot discovery is enabled on the server (see
BootNoMulticastDiscovery), this option must be set to the multicast IP address
used by the remote-boot clients when performing PXE discovery.
If this option is not set, REMBO uses the IP address 232.2.0.1
If the REMBO server is in the same subnet as the DHCP server, PXE discovery is
not required because the remote-boot clients will know that the PXE server (i.e.
REMBO) is on the same computer as the DHCP server (option 60 set to
PXEClient). If the REMBO server and the DHCP server run on different machines,
but are on the same IP subnet, PXE discovery is still not required because the
REMBO server will intercept DHCP requests and will provide PXE information at
the DHCP stage. You only require PXE discovery if the remote-boot clients are not
on the same subnet as the REMBO server, or if your existing PXE infrastructure is
already setup for PXE discovery.

Example
BootDiscoveryAddress 232.5.6.7

56
BootDiscoveryPort
BootDiscoveryPort — IP port used when listening to PXE discovery requests
Synopsis

BootDiscoveryPort port

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
This parameter must be set to the port used by remote-clients when sending PXE
boot requests (multicast boot discovery, or BINL discovery). The default value
works with out-of-the-box PXE bootroms, so there is no reason to change this value
unless you know what you are doing.
If this option is not set, REMBO uses the IP port 4011.

Example
BootDiscoveryPort 5011

57
BootNoMulticastDiscovery
BootNoMulticastDiscovery — Disable PXE multicast discovery support
Synopsis

BootNoMulticastDiscovery yes/no

Location in the configuration

• Server console:\Parameters\Advanced
• File-based:Beginning of the file

Description
If the parameter BootNoMulticastDiscovery (without argument) is present in the
configuration file (file-based config), then PXE multicast discovery is disabled on
the server. The REMBO server will not answer PXE multicast packets received
from remote-boot clients.
If the configuration is stored in the registry, if the parameter
BootNoMulticastDiscovery and is set to yes, then PXE multicast discovery is
disabled on the server. The default value is no.
PXE multicast discovery is used by remote-boot clients if your existing PXE
infrastructure is configured to use PXE discovery. Multicast discovery is not needed
if the remote-boot clients and the REMBO server are on the same subnet, as the
clients will use other mechanisms to find the REMBO server (DHCP proxy, or
DHCP option 60).
If you know that you do not need PXE multicast discovery, you can disable it by
setting this parameter to true. This is suggested if you are in a large company or
institution where other PXE clients may be configured to use multicast discovery on
other subnets, but you do not want your server to reply to these clients.

Example
BootNoMulticastDiscovery

58
BootReplyDelay
BootReplyDelay — Set the delay before answering discovery requests
Synopsis

BootReplyDelay secs

Location in the configuration

• Server console:\Parameters\Advanced
• File-based:Beginning of the file

Description
This parameter sets the number of seconds to wait before answering a PXE
discovery request (PXE discovery enabled), or a DHCP request (ProxyDHCP
enabled). The default value is 0 (no delay).
The only reason to delay a PXE reply is when two or more REMBO servers are
configured to run on the same subnet, with the same list of hosts. The master server
could be configured with a delay of 0 seconds (answer immediately), and other
servers with a delay of 2 seconds. If the master server fails, backup servers will
handle remote-boot clients requests. See Section 4.1 for more information on
fault-tolerance.

Example
BootReplyDelay 2

59
DataDir
DataDir — Directory for internal files
Synopsis

DataDir "path"

Location in the configuration

• Server console:\Parameters\Advanced
• File-based:Beginning of the file

Description
The server uses the directory specified by DataDir to store its internal files, in
particular all the files stored on its filesystem.
You can use this parameter to specify a new directory for the internal files of the
server, for example if you want to store the server files on a new storage device with
more space, but you want to keep the executable and configuration files on the
original location.
All the files stored in the directory specified by DataDir should not be modified, or
the REMBO server may not work properly. If the specified directory does not
exists, the server will try to create it.

Examples
DataDir "/mnt/morespace/rembo"
DataDir "d:/rembo"

60
SharedDir
SharedDir — Base directory for shared repository
Synopsis

SharedDir "path"

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
This is the path where Rembo stores the shared repository for shared archives.

Examples
SharedDir "/mnt/commonspace/rembo"
SharedDir "d:/shared"

61
DisableDHCPProxy
DisableDHCPProxy — Disable answers to DHCP discovers (DHCPProxy)
Synopsis

DisableDHCPProxy yes/no

In file-based configuration, the keyword DisableDHCPProxy is used without


argument. If the keyword is present, it is assumed to be set to the value yes
automatically.

Location in the configuration

• Server console:\Parameters\Advanced
• File-based:Beginning of the file

Description
If this parameter is set to yes, then the REMBO server will not send PXE replies to
DHCPDISCOVER packets sent by remote-boot clients. You can set this parameter
to yes if you do not need this feature because either the DHCP server and the
REMBO server are on the same host, or you are using PXE multicast discovery.
The default value is false (i.e. DHCP Proxy is enabled by default).

Example
DisableDHCPProxy

62
DisableBOOT
DisableBOOT — Disable PXE services
Synopsis

DisableBOOT

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
Use this option to disable the PXE component of the Rembo server. Clients will not
be able to boot on PXE anymore if this option is included in the configuration file.
Use this option if you want to use the Rembo server for remote file access only (e.g.
when setting up the server)
Not included in the default configuration.

Example
DisableBOOT

63
DisableNBP
DisableNBP — Disable NBP services
Synopsis

DisableNBP

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
Including this option in the configuration file causes the NBP component of the
Rembo server to stop answering requests coming on the NBP port. Do not set this
option if your server is used by Rembo clients
Not included in the default configuration.

Example
DisableNBP

64
DisableFILE
DisableFILE — Disable FILE (NetFS, MCAST) services
Synopsis

DisableFILE

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
Add this option to the configuration file if you want to disable the FILE
(NetFS,MCAST) component of the Rembo server. This can be useful if you are
accessing the server from TCP clients like RABAgent only. Do not set this option if
clients are booting on this server
Not included in the default configuration.

Example
DisableFILE

65
DisableTCP
DisableTCP — Disable TCP services
Synopsis

DisableTCP

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
Include this option if you are not using server synchronization or if this this option
if you are not using server synchronization or if this server is not used as a RAB
server. This will disable the TCP component of the Rembo server
Not included in the default configuration.

Example
DisableTCP

66
FASTEncrypt
FASTEncrypt — Encrypt FAST datagrams
Synopsis

FASTEncrypt

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
If this parameter is present in a file-based configuration file, or set to yes in the
server console, FAST datagrams exchanged between the server and the remote-boot
clients will be encrypted.
The FAST protocol is used by remote-boot clients to send large files to the server.
This protocol is a proprietary protocol made for REMBO, using unicast UDP.
FAST datagrams are not encrypted by default.

Example
FASTEncrypt

67
FASTPort
FASTPort — Port used for FAST transfers
Synopsis

FASTPort port

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
This parameter defines which port to use on the server for transfers using the FAST
protocol. The default value is 4025.
Change this value if you think that the port 4025 is already used by another network
service running on your server.
The FAST protocol is used by remote-boot clients to send large files to the server.
This protocol is a proprietary protocol made for REMBO, using unicast UDP.

Example
FASTPort 4025

68
MaxPCASTSessions
MaxPCASTSessions — Maximum number of simultaneous PCAST sessions
Synopsis

MaxPCASTSessions number

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
This is the maximum number of PCAST sessions that the server will accept
simultaneously. This parameter is mostly relevant if the server is running in
UNICAST mode and deploying a group with UNICAST setting.
The default value is 8. Since each session uses around 16Mb of server memory,
higher values should be avoided on servers with no more than 256Mb.

Example
MaxPCASTSessions 8

69
FileMCASTAddress
FileMCASTAddress — Multicast address used for the MCAST protocol
Synopsis

FileMCASTAddress ip-addr:port

FileMCASTAddrCount number

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
FileMCASTAddress defines the destination multicast address and destination port
used by the server when sending multicast UDP datagram to clients requesting a file
with the MCAST protocol. The default value is 239.2.0.1:10000.
FileMCASTAddrCount defines the upper limit of the multicast address range used by
the server (i.e. the number of different multicast addresses used). When combined
with FileMCASTAddress, this parameter can control the lower and upper limits of
the range of multicast addresses used by the server. The default value is 256 (i.e. use
no more than 256 multicast addresses).
The MCAST protocol is used by remote-boot clients to download large files from
the server. This protocol is a proprietary protocol made for REMBO, using
multicast UDP.

Example
To force the server to use 1000 multicast addresses starting at 232.1.1.1, use:
FileMCASTAddress 232.1.1.1
FileMCASTAddrCount 1000

70
FileMCASTEncrypt
FileMCASTEncrypt — Encrypt MCAST datagrams
Synopsis

FileMCASTEncrypt

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
If this parameter is present in a file-based configuration file, or set to yes in the
server console, MCAST datagrams exchanged between the server and the
remote-boot clients will be encrypted.
The MCAST protocol is used by remote-boot clients to download large files from
the server. This protocol is a proprietary protocol made for REMBO, using
multicast UDP.
MCAST datagrams are not encrypted by default.

Example
FileMCASTEncrypt

71
FileMCASTTTL
FileMCASTTTL — Time-To-Live used for MCAST datagrams
Synopsis

FileMCASTTTL ttl

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
The value defined by this parameter is used by the REMBO server as the
Time-To-Live parameter for UDP datagrams sent to remote-boot clients with the
MCAST protocol. The default value is 1 (cross no router).
Read the discussion about TTLs in the manual page of MTFTPMCastTTL for more
information about TTL values.
The MCAST protocol is used by remote-boot clients to download large files from
the server. This protocol is a proprietary protocol made for REMBO, using
multicast UDP.

Example
FileMCASTTTL 5

72
FileServerPort
FileServerPort — Port used on the server for NETfs, MCAST & FAST
requests
Synopsis

FileServerPort port

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
This value is used by the server as the port for all file-related requests sent by
remote-boot clients. File-related requests include NETfs requests, MCAST requests
and FAST requests.
The default value is 4013. The value of this parameter is sent to REMBO clients
during the NBP phase of the boot process. If you change this parameter, clients will
automatically use the new value on next boot.

Example
FileServerPort 5013

73
TCPServerPort
TCPServerPort — Define the TCP port used
Synopsis

TCPServerPort port

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
This option defines the TCP port used by the TCP component of the Rembo server
when listening to requests coming from other servers or RABAgent.
The default value is 2048

Example
TCPServerPort 2048

74
Interfaces
Interfaces — List of network interfaces used by the server
Synopsis

Interfaces ip-addr1 [ip-addr2] [ip-addr3 ...]

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
You will find this option very usefuly if you are running REMBO on a multihomed
server (i.e. a host with more than one network card, or with a network card and a
dial-up adapter).
This option lets you specify the list of network interfaces used by the server when
receiving and sending packets to REMBO clients. If you leave this option unset, the
server will use the network interface corresponding to the official hostname of the
server.
You must specify a list of IP addresses to use. Each IP address must correspond to
the IP address of one of the server’s network interfaces. The list must contain at
least one address.

You are strongly encouraged to set this option if your server is multihomed.
Otherwise the server may not receive the network packets not originating from
its official interface.

Examples
Interfaces 192.168.1.1
Interfaces 192.168.1.1 192.168.10.1 10.1.1.1

75
MaxLogSize
MaxLogSize — Maximum size of log files created by the server
Synopsis

MaxLogSize size_in_bytes

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
This parameter can be used to limit the size of the log file generated by the REMBO
server. The maximal log size must be specified in bytes, and apply to all the log files
created by the server (file,nbp and boot). If you do not specify this parameter, or set
the limit to 0, then log files are not limited in size.

Example
To limit the size of logs to 10MB:
MaxLogSize 10000000
To disable log size limit:
MaxLogSize 0

76
MTFTPClients
MTFTPClients — The destination address and port used by the MTFTP server
Synopsis

MTFTPClients ip-addr [:port]

Location in the configuration

• Server console:\Parameters\Advanced
• File-based:Beginning of the file

Description
This is the destination IP address and port used by the server when sending
multicast MTFTP datagram to clients. The IP address must be a valid multicast
address and must match the address sent to the remote-boot client during the DHCP
phase. If the remote-boot client has received its PXE parameters from the REMBO
server during the DHCP phase, this address is automatically included so that the
client always uses the same address/port as the server.
The default value is 232.1.0.1:8500.

Example
MTFTPClients 232.8.7.6

77
MTFTPMCastTTL
MTFTPMCastTTL — The TTL used for MTFTP multicast datagrams
Synopsis

MTFTPMCastTTL ttl

Location in the configuration

• Server console:\Parameters\Advanced
• File-based:Beginning of the file

Description
This parameter defines the Time-To-Live (TTL) associated with MTFTP multicast
packets sent to remote-boot clients. The TTL value is used by network routers to
determine if a packet can be forwarded further, or should be discarded. Each router
decrements the value by 1 when it forwards the packet further, and if a router
receives a packet with a TTL of 1, the packet is discarded instead of being
forwarded.
You can think of the MCastTTL as the number of routers minus 1 that your
multicast packets will be able to cross. If you set this value to 1, multicast packets
will not be forwarded by any router, and will therefore stay on the local subnet. If
you set this value to 4, multicast packets will cross 3 routers before being discarded.
The default value is 1.

Example
MTFTPMCastTTL 5

78
MTFTPPort
MTFTPPort — The port used by the MTFTP server
Synopsis

MTFTPPort port

Location in the configuration

• Server console:\Parameters\Advanced
• File-based:Beginning of the file

Description
This is the port used by the server when listening to MTFTP requests. If the
remote-boot client are using the REMBO server to get their PXE parameters, this
value is sent in the DHCP/PXE reply so that the remote-boot client always uses the
proper port.
The default value is 4015.

Example
MTFTPPort 5015

79
MTFTPStartDelay
MTFTPStartDelay — The initial delay on clients before sending first MTFTP
request
Synopsis

MTFTPStartDelay secs

Location in the configuration

• Server console:\Parameters\Advanced
• File-based:Beginning of the file

Description
This is the delay used by remote-boot clients before sending the first MTFTP
request to the server. This delay is used by the client to listen to an existing MTFTP
transfer. If the MTFTP file they are about to request is already being sent by the
server on the multicast address, then the client will not request the file and will
simply listen to the packets. The longer this delay is, the more probability you have
that many clients will reuse the same MTFTP channel instead of requesting the file.
But if you want to have a fast boot process, you should set this value to 1 (the
minimum value).
The default value is 2 (seconds).

Example
MTFTPStartDelay 1

80
NBPServerPort
NBPServerPort — Port used on the server for NBP requests
Synopsis

NBPServerPort port

Location in the configuration

• Registry-based:\Parameters\Advanced
• File-based:Beginning of the file

Description
This value is used by the server as the port for all NBP requests sent by remote-boot
clients. NBP is a protocol used by REMBO clients to get their startup parameters
(startup page, groupname, ...) and to send authentication requests to the server.
The default value is 4012. The value of this parameter is sent to REMBO clients as
part of the last MTFTP packet when the server sends the initial part of REMBO to
the PXE bootrom. If you change this parameter, clients will automatically use the
new value on next boot.

Example
NBPServerPort 5012

81
NetPassword
NetPassword — Network password for remote file access
Synopsis

NetPassword "password"

Location in the configuration

• Registry-based:\Parameters
• File-based:Beginning of the file

Description
This is the password used by the server to accept or deny network requests coming
from a REMBO client, the server console or NetClnt.
You must change this option when you install a new REMBO server and choose a
password to protect your files against illegal access. If you are using the Windows
NT version of the server, you are asked to enter the password during the setup.
If you are using the server console, or NetClnt to access the files stored in your
REMBO server, the password you enter in NetClnt (or the server console if you are
using the "remote server" type of server) must match the word set in NetPassword.
However, if you are using the server console to access a local REMBO server, or
remote NT server, you do not need to enter the password, as the console is able to
get the password in the registry.

This password is an important piece of your REMBO security. If you require


optimal security, you are strongly encouraged to protect the configuration of
the server. If you are running the server on Windows NT, you should change
the security on the
SYSTEM/CurrentControlSet/Services/RemboServer/Parameters registry key (use
REGEDT32.EXE). If you are running the server on a Unix computer, you should
change the file mode on the configuration file with chmod.

Example
NetPassword "mypassword"

82
II. Authentication domains reference
Table of Contents
AuthLocalDomain .................................................................................................. 85
AuthNTDomain ...................................................................................................... 86
AuthRadiusDomain ............................................................................................... 87

83
Authentication domains reference
AuthLocalDomain
AuthLocalDomain — Local authentication domain
Synopsis

AuthLocalDomain
AuthLocalDomain { UserGroup "group" }

Location in the configuration

• Registry-based:\Parameters\AuthDomains
• File-based:After global parameters

Description
Local authentication domain.

Example
AuthLocalDomain {
UserGroup "rembousers"
}

85
AuthNTDomain
AuthNTDomain — Remote NT authentication domain
Synopsis

AuthNTDomain { AuthServerName "hostname" UserGroup "group" }

Location in the configuration

• Registry-based:\Parameters\AuthDomains
• File-based:After global parameters

Description
Remote NT authentication domain.
privileges

Example
AuthNTDomain {
AuthServerName "domain-pdc"
UserGroup "rembousers"
}

86
AuthRadiusDomain
AuthRadiusDomain — Radius authentication domain
Synopsis

AuthRadiusDomain { AuthServerAddress ip-addr RadiusSecret "secret" }

Location in the configuration

• Registry-based:\Parameters\AuthDomains
• File-based:After global parameters

Description
Radius authentication domain.

Example
AuthRadiusDomain {
AuthServerAddress 192.168.1.15
RadiusSecret "testing123"
}

87
III. TCP tunnels reference
Table of Contents
RemoteHost ............................................................................................................ 90
RemotePort ............................................................................................................. 91

88
TCP tunnels reference
RemoteHost
RemoteHost — Hostname or IP address of remote TCP host
Synopsis

RemoteHost "host"

Location in the configuration

• Registry-based:\Parameters\TCPTunnels
• File-based:After global parameters

Description
RemoteHost is a string representing the TCP remote host to contact when a REMBO
client opens this TCP tunnel. You can either specify a hostname or an IP address for
this parameter. Note that you need to use double quotes (") around the hostname or
IP address if you are using file-based server configuration.

Examples
TCPTunnel finger {
RemoteHost "finger.company.com"
RemotePort 79
}

TCPTunnel ODBC {
RemoteHost "127.0.0.1"
RemotePort 2020
}

90
RemotePort
RemotePort — Numerical TCP port of remote connection
Synopsis

RemotePort port

Location in the configuration

• Registry-based:\Parameters\TCPTunnels
• File-based:After global parameters

Description
RemotePort is a number representing the TCP port to connect to when a REMBO
client opens this TCP tunnel. You can get the complete list of valid port numbers in
the file /etc/services on any Unix computer, or in the file
/winnt/system32/drivers/etc/services on a Windows NT computer.

Examples
TCPTunnel finger {
RemoteHost "finger.company.com"
RemotePort 79
}

TCPTunnel ODBC {
RemoteHost "127.0.0.1"
RemotePort 2020
}

91
IV. Host groups parameters reference
Table of Contents
AuthDomain ........................................................................................................... 94
FileServer................................................................................................................ 95
Host.......................................................................................................................... 96
HostRange............................................................................................................... 97
PXEBootMode........................................................................................................ 98
Lockout ................................................................................................................... 99
Options .................................................................................................................. 100
RemoteConsole..................................................................................................... 102
StartPage............................................................................................................... 103

92
Host groups parameters reference
AuthDomain
AuthDomain — Authentication domain
Synopsis

AuthDomain "domain"

Location in the configuration

• Registry-based:\Parameters\Group
• File-based:In a group statement

Description
This is the name of the authentication domain to use when a remote-boot client
sends an authentication request to the server for identifying a user. This name must
match the name of an existing authentication domain as defined in Section 2.3.
This parameter is applied to all the hosts contained in the group.

Example
Group MyGroup {
AuthDomain "lcltest"
Host 192.168.1.4
}

94
FileServer
FileServer — Define a new server for FILE services
Synopsis

FileServer ip-addr

Location in the configuration

• Registry-based:\Parameters\Group
• File-based:In a group statement

Description
This parameter can be used to specify the IP address of the host serving the NETfs,
FAST and MCAST protocols. If the you want to use the same REMBO server for
all services, you do not have to specify this parameter.
The host defined by this parameter must be configured to use the same network
password (NetPassword) as the server containing this parameter.
This parameter is applied to all the hosts contained in the group.

Example
Group MyGroup {
FileServer 172.16.8.9
Host 192.168.1.4
HostRange 192.168.1.5 -> 192.168.1.10 {
FileServer 172.16.10.10
}
}

95
Host
Host — Host entry in a host list
Synopsis

Host ip-addr
Host hw-addr

Location in the configuration

• Registry-based:\Parameters\Group
• File-based:In a group statement

Description
This parameter defines a host in a group host list. The argument can be either an IP
address (192.168.1.1) or a hardware address (00:10:4b:12:34:56).
You can define host-specific options by adding a block of parameters after the host
statement. The block of parameters must start with { and end with }.
Please note that if you are using IP addresses to identify remote-boot clients, the
server will be unable to match a DHCP request with a client entry if you are using
the DHCPProxy mode for PXE discovery. This is due to the fact that the client has
no IP address when it sends the DHCP request.

Example
Group MyGroup {
StartPage "net://group/start.html"
Host 192.168.1.4
Host 00:10:4b:12:34:56 {
StartPage "net://global/page123456.html"
}
}

96
HostRange
HostRange — Host range entry in a host list
Synopsis

HostRange startip -> endip

Location in the configuration

• Registry-based:\Parameters\Group
• File-based:In a group statement

Description
This parameter defines a range of hosts in a group host list. The argument is the first
IP address and the last IP address of the range.
You can define host-specific options by adding a block of parameters after the
hostrange statement. The block of parameters must start with { and end with }.

Example
Group MyGroup {
StartPage "net://group/start.html"
HostRange 192.168.1.4 -> 192.168.1.6
HostRange 192.168.1.10 -> 192.168.1.20 {
StartPage "net://global/page123456.html"
}
}

97
PXEBootMode
PXEBootMode — Select PXE boot behaviour
Synopsis

PXEBootMode { normal | hdboot | ignore}

Location in the configuration

• Registry-based:\Parameters\Group
• File-based:Beginning of the file

Description
This option defines how REMBO answers PXE boot requests coming from clients
in this group. When mode is ’normal’, REMBO will process the boot request. When
mode is ’hdboot’, REMBO will tell the client to immediately boot on the hard disk.
When mode is ’ignore’, REMBO will not answer the boot request, thus giving the
opportunity for another PXE server to answer
Not included in the default configuration.

Example
PXEBootMode normal

98
Lockout
Lockout — Lock peripherals on the remote client
Synopsis

Lockout [none] [, poweroff] [, reset] [, mouse] [, keys] [,


screen] [, all]

Location in the configuration

• Registry-based:\Parameters\Group
• File-based:In a group statement

Description
Use this parameter to lock peripherals on the remote-boot clients during the time
REMBO is active on the remote computer. You can for example lock the mouse
or/and the keyboard so that the user cannot interrupt an automatic image restoration
process.
Peripherals are automatically unlocked when REMBO gives the control to the
operating system (with a HDBoot, LXBoot, RDBoot or DeviceBoot).
This parameter can also be used in conjunction with the RemoteConsole parameter
for having full control on a remote computer.
This parameter is applied to all the hosts contained in the group.

Example
Group MyGroup {
Lockout keys, mouse
RemoteConsole 172.16.5.6
Host 192.168.1.4
HostRange 192.168.1.5 -> 192.168.1.10 {
Lockout all
}
}

99
Options
Options — Startup options for the remote client
Synopsis

Options [admin] [, autoboot] [, novesa] [, noudma] [, nocache] [,


unicast]

Location in the configuration

• Registry-based:\Parameters\Group
• File-based:In a group statement

Description
Four different options can be set for REMBO clients. These options are used when
the remote-boot client enters REMBO:

• Admin: force the client to run in administrative mode. Administrative mode adds
options in the start menu on the client: Interact, to run the interactive evaluator,
and Purge cache to purge the local disk cache. Additionnally, functions defined
in the admin.rbx plugins are available (File Manager, TextEdit, ...).
• Autoboot: tells REMBO to automatically reboot on fatal errors. Fatal errors are
low-level errors which cannot be intercepted with the exception mechanisms
defined at the Rembo-C level. By default fatal errors are displayed on the screen
and the computer is halted. You can define the autoboot option if you want to
reboot on fatal errors.
• NoVESA: disables all the graphical interface on the remote-boot client.
• NoUDMA: disables UltraDMA support for all IDE hard-disks on the remote-boot
client. This can solve problems on poorly designed hardware or buggy chipsets,
but at a high cost in terms of performance.
• NoCache: disables the use of Rembo special cache partition (disk://0:-1). Use
this option if you want Rembo to to try to cache the overlay when booting, in
order to leave the hard-disk completely unchanged regardless of the partition
scheme.
• Unicast: use unicast instead of multicast when downloading files from the
server.

100
Options
This parameter is applied to all the hosts contained in the group.

Example
Group MyGroup {
Options admin
Host 192.168.1.4
HostRange 192.168.1.5 -> 192.168.1.10 {
Options autoboot
}
Host 192.168.1.30 {
Options autoboot
}
}

101
RemoteConsole
RemoteConsole — Define a remote-console host
Synopsis

RemoteConsole ipaddr:port

Location in the configuration

• Registry-based:\Parameters\Group
• File-based:In a group statement

Description
This parameter defines the IP address and port for the Remote Console application,
and instructs REMBO to contact the Remote Console at next boot.
You can use the Remote Console windows application (RConsole.exe) to remotely
control the mouse, keyboard and screen of a remote-boot client from a Windows
computer. Remote-console mode must be activated on the client, either by setting
the RemoteConsole parameter in the group definition for the client, by using the
wizards or by executing the RConsole Rembo-C function.
This parameter can also be used in conjunction with the Lockout parameter for
having full control on a remote computer.
This parameter is applied to all the hosts contained in the group.

Example
Group MyGroup {
Lockout keyboard, mouse
RemoteConsole 172.16.5.6
Host 192.168.1.4
HostRange 192.168.1.5 -> 192.168.1.10 {
Lockout all
}
}

102
StartPage
StartPage — REMBO startup page
Synopsis

StartPage "path"

Location in the configuration

• Registry-based:\Parameters\Group
• File-based:In a group statement

Description
This parameter defines the HTML page loaded by the REMBO client on startup.
You can use this parameter to assign different startup pages on a per-group basis.
The "path" argument must be a valid REMBO URL.
This parameter is applied to all the hosts contained in the group.

Example
Group MyGroup {
StartPage "net://group/start.html"
Host 192.168.1.4
HostRange 192.168.1.5 -> 192.168.1.10 {
StartPage "net://global/start2.html"
}
}

103
Appendix A. Sample configuration file
This appendix contains a sample configuration file. All parameters are included, but
only those who are in the minimal configuration set are uncommented. All other
parameters are shown here for reference.
The configuration file is named rembo.conf. It is made of three parts: global
parameters, authentication domains and host groups.

Comments can be inserted anywhere in the file after a #. Braces are used to delimit
blocks. Double quotes are used to delimit string arguments. There is no need for
semicolon between settings, since the use of quoted strings already makes the
description unambiguous.
# Sample Rembo Server config file for Rembo 2.0 Toolkit
#
#

#--------------------------------#
# BASIC CONFIGURATION PARAMETERS #
#--------------------------------#

# BaseDir <string>
# Specifies the home dir for the server. All paths can then be
# specified as relative to this base directory
# e.g. Basedir "c:/bootrom/rembo"
BaseDir "/usr/local/rembo"

# NetPassword <string>
# This password is used by the Rembo server to protect its files
# agains an illegal use through the NETfs client (netclnt).
# This option is mandatory.
NetPassword "please set a password here"

# Interfaces <ip-addresses>
# This is the list of IP addresses used by the Rembo server to send and
# receive packets. Use this parameter if you have more than one interface
# on your server, or if you are seeing problems with multicast transfers
# e.g. Interfaces 192.168.1.1 192.168.2.1 192.168.3.1

# DataDir <string>
# This is the path of the directory used by the Rembo server for
# storing its filesystem
DataDir "files" #default value

# SharedDir <string>
# This is the path where Rembo stores the shared repository for
# shared archives.
default: "shared" #default value

# Backup <ipaddr>
# Use this statement to define a Rembo backup server. The server will
# be used by Rembo hosts when the primary server fails.

104
Appendix A. Sample configuration file
# (see also ProxyDelay)
# e.g. Backup 192.168.1.8

# BootReplyDelay <interval-in-seconds>
# This parameter defines how many seconds to wait before sending a
# reply packet to a DHCP discovery packet (Proxy or Boot). In most cases,
# you will set this parameter to 0 (immediate reply, the default value). If
# this server is a Rembo backup server, set this parameter to a small positive
# value, for example 2. This will instruct the server to wait 2
# seconds before answering the DHCP discovery packet. This will make
# sure that this server never answers before the primary server.
# You can set this parameter to 0 on a backup server if you want to
# implement load-balancing: the fastest (less loaded) server will answer first.
BootReplyDelay 0 # default value

# DisableDHCPProxy
# This option is only used if the DHCP server and the Rembo server
# are running on different hosts. By default, the Rembo server
# intercepts DHCP dialog messages and sends PXE specific options to
# the remote-boot clients. If you define the DisableDHCPProxy parameter,
# the Rembo server will stop to intercept these packets.
# You can use this option if your DHCP server is configured to send PXE
# options (DHCP option 43) in DHCP offers.
# This parameter has no effect if the Rembo server and the DHCP server both
# run on the same host.
# default: not included in the configuration

# MTFTPMCastTTL <number>
# You can modify the multicast TTL (time-to-live) used in MTFTP
# packets. The default value is 1. You can view multicast TTL as the
# maximum number of routers that a multicast packet will cross. A
# value of 1 means "no routing" (packets will stay on the local
# subnet), whereas a value greater than 1 means "cross n-1 routers".
# Note: set this value to at least ’2’ if you are using multicast over
# routed VLANs
MTFTPMCastTTL 1 #default value

# FileMCASTTTL <number>
# Use this value if you want to use the MCAST protocol across
# routers. See the MCastTTL parameter in the BOOTServer for more
# details. Default value is 1 ("cross no router")
# Note: set this value to at least ’2’ if you are using multicast over
# routed VLANs
FileMCASTTTL 1 #default value

# MaxLogSize <size-in-bytes>
# Use this option to limit the size of logs generated by the Rembo server
# e.g. MaxLogSize 65000
MaxLogSize 0 # default value (no limit)

# --------------------------------------------------------------
# Define your authentication domains here. You can then refer to
# these domains in the host groups. Authentication
# domains can be of three types: Local, NTAuth or Radius.

105
Appendix A. Sample configuration file

# AuthLocalDomain <identifier> or <identifier> { auth-options }


# Defines a new local domain named <identifier>. A local domain
# is a domain where users are authenticated against server’s local
# authentication services. If your server is a Linux server, users
# in a local domain will be authenticated using the /etc/passwd file
# or a NIS/NIS+ service if there is one.
# If your server is a NT server, users in a local domain will be
# authenticated against local users (users known by the server).
#
AuthLocalDomain lcltest1
AuthLocalDomain lcltest2 {
# UserGroup <string>
# Defines a NT/Unix group in which users must exist in order
# to be successfully authenticated. This is an optional
# statement (if not specified, all the users will be
# accepted)
UserGroup "rembo"
}

# AuthNTDomain <identifier> { auth-options }


# This option is only available when your server is running on a
# Windows NT computer. It allows you to check rembo users against
# a remote NT user database.
#
AuthNTDomain ntatest {
# AuthServerName <string>
# This is the computer name of the remote computer to use
# for the authentication
AuthServerName "company-pdc"
# see AuthLocalDomain for a description of the UserGroup option
UserGroup "rembo"
}

# AuthRadiusDomain <identifier> { auth-options }


# This statement can be used to define a Radius authentication domain.
# Rembo hosts configured to use this domain will have their user
# auth credentials checked against a Radius auth server database.
AuthRadiusDomain radtest {
# AuthServerAddress <ipaddr:port> or <ipaddr>
# This is the IP address of the Radius server
AuthServerAddress 192.168.1.15
# eg: AuthServerAddress 192.168.1.15:1615

# RadiusSecret <string>
# This is the secret to use for signing authentication
# packets sent to the Radius server. See your Radius
# documentation for more details.
RadiusSecret "testing123"
}

# --------------------------------------------------------------
# Define your TCP tunnels here. Read the server’s manual for more
# information on TCP tunnels.

106
Appendix A. Sample configuration file

TCPTunnel sendmail {
# RemoteHost <host>
# Use this option to specify the IP address for the destination
# of this TCP tunnel. Requests received for this TCP tunnel will
# be forwarded to this host.
# Note: the host can be specified by a name or by a quoted IP adress
RemoteHost "192.168.1.10"

# RemotePort <port>
# Use this option to specify the target TCP port to connect to when
# forwarding TCP traffic coming from Rembo clients
RemotePort 25
}

#-------------#
# HOST GROUPS #
#-------------#

# This section defines specific parameters on a host or group basis. You


# can set a different parameter for each host, or decide to group several
# hosts together to share parameter values.

# Every group except the Default group must include a host list. This list
# enumerates the hosts belonging to this group. A special group, named the
# Default group, is used by hosts not declared in any group.

#
# GROUP <identifier>
#
# A group definition has the following syntax:
#
# GROUP <identifier> {
# group-options
#
# hosts-declaration
# }
# Note: the hosts-declaration statement can contain per-host
# group-options
#
# Note: if you name a group "Default", this group will be used for
# hosts not declared in any group. If there is no Default
# group, hosts not found in any group will be refused to
# use this server.
#
GROUP RemboTest {
#
# FILEServer <ipaddr> or <ipaddr>, <ipaddr>
# FILEServer <ipaddr:port> or <ipaddr:port>, <ipaddr:port>
#
# This is the IP address of the MCAST & NETfs server to
# connect to. This parameter is optional. If not specified, the
# file server address will be the primary IP address of this
# host (the host running the server).

107
Appendix A. Sample configuration file
# You can use this option to redirect hosts to a different
# file server.
# e.g. FILEServer 192.168.1.3, 192.168.1.5:4013

#
# Options admin, autoboot, novesa, noudma, nocache, unicast
#
# These options modify Rembo’s behaviour in the following way:
# admin: load admin.rbx plugins and enable interactive window
# novesa: disable the graphical interface
# noudma: disable UltraDMA support (slow !)
# nocache: disable the use of Rembo cache partition
# autoboot: automatically reboot when a major fault has occured
# unicast: use unicast when sending files to hosts in this group
#
# note: you can set multiple options, separated with commas
# e.g. Options admin, unicast
Options admin

#
# PXEBootMode normal / hdboot / ignore
#
# This option defines how Rembo answers PXE boot requests coming
# from clients in this group.
# If mode is ’normal’, Rembo will process the boot request
# If mode is ’hdboot’, Rembo will tell the client to immediately
# boot on the hard disk
# If mode is ’ignore’, Rembo will not answer the boot request, thus
# giving the opportunity for another PXE server to answer
#
PXEBootMode normal # default value

#
# RemoteConsole <ipaddr> or <ipaddr:port>
#
# Enable the RemoteConsole feature at startup. The host
# specified in the IP address must be running the Windows
# Remote Console application.
# eg. RemoteConsole 192.168.1.10

#
# Lockout none, poweroff, reset, mouse, keys, screen, all
#
# The Lockout parameter can be used to lock parts of the
# computer input/output devices during the execution of
# Rembo
# e.g Lockout keys, mouse
Lockout none # default value

#
# StartPage <url-path>
#
# This is the path to Rembo’s startpage. This file will
# be downloaded and displayed on Rembo’s screen at

108
Appendix A. Sample configuration file
# startup.
# e.g. StartPage "net://global/rembo.shtml"

#
# AuthDomain <identifier>
#
# This is the authentication domain to use when a client
# wants to check a username/password credential pair. Use
# an identifier previously defined in the "Global" section.
# e.g. AuthDomain "radtest"

#
# Definition of hosts
# -------------------
#
# Format:
#
# Host <ipaddr>
# Host <ipaddr> { group-options }
# Host <macaddress>
# Host <macaddress> { group-options }
# HostRange <firstip> -> <lastip>
# HostRange <firstip> -> <lastip> { group-options }
#
# Examples:
Host 192.168.1.118
Host 192.168.1.119 {
StartPage "net://global/special.html"
}
Host 00:10:4b:12:12:12

HostRange 192.168.2.1 -> 192.168.2.254

HostRange 192.168.3.1 -> 192.168.3.100 {


AuthDomain "lcltest"
}
}

#-----------------------#
# ADVANCED OPTIONS #
#-----------------------#

#
# PXE Boot Options
# ----------------
#
# The PXE Boot Server is responsible for answering PXE discovery requests
# directed to Rembo servers (PXE ID 15). The PXE Boot Server is also
# responsible for sending Rembo’s initial bootstrap program (a 30kb program
# used to download Rembo).

# DisableBOOT
# Use this option to disable the PXE component of the Rembo server. Clients
# will not be able to boot on PXE anymore if this option is included in the

109
Appendix A. Sample configuration file
# configuration file. Use this option if you want to use the Rembo server
# for remote file access only (e.g. when setting up the server)
# default: not included in the configuration

# BootDiscoveryPort <port>
# This options modifies the port used by Rembo server when listening to
# PXE BINL requests.
BootDiscoveryPort 4011 # default value

# BootDiscoveryAddress <ipaddr>
# This is the multicast discovery address which will be used by
# Rembo’s server when listening to PXE Boot discovery requests.
BootDiscoveryAddress 232.2.0.1 # default value

# BootNoMulticastDiscovery
# If you set this parameter, the Boot Server will not listen to
# multicast discovery requests anymore. Use this parameter only if
# you must disable multicast discovery and you know how to setup
# unicast discovery in the DHCP configuration.
# default: not included in the configuration

# MTFTP options
# -------------
# MTFTP is the protocol used by PXE to download Rembo’s
# initial bootstrap program.

# MTFTPPort <port>
# This options modifies the port used by Rembo server when listening to
# multicast TFTP (MTFTP) requests coming from clients.
MTFTPPort 4015 # default value

# MTFTPClients <ipaddr> or <ipaddr:port>


# This is the multicast address and destination port used for MTFTP
# packets sent to MTFTP clients.
MTFTPClients 232.1.0.1:8500 #default value

# MTFTPStartDelay <delay-in-seconds>
# This is the number of seconds a MTFTP client will listen before
# starting the MTFTP transfer. The default is 2. If you use a larger
# value, clients will have a increased possibility of being
# synchronized, thus improving performance.
MTFTPStartDelay 2 #default value

#
# FILE server
# -----------
#
# Rembo’s FILE server implements the two file transfer protocols used by
# the client computer running Rembo: MCAST and NETfs.

# DisableFILE
# Add this option to the configuration file if you want to disable the
# FILE (NetFS,MCAST) component of the Rembo server. This can be useful if
# you are accessing the server from TCP clients like RABAgent only. Do not

110
Appendix A. Sample configuration file
# set this option if clients are booting on this server
# default: not included in the configuration

# FileServerPort <port>
# This parameters modify the port used by the server
# when listening to MCAST requests
FileServerPort 4013 # default value

# MaxPCASTSessions <number>
# This specifies the maximum number of simultaneous PCAST sessions handled
# by the server.
# This parameter is mostly relevant when the server is set to work with
# UNICAST protocol and the group to deploy is also set to UNICAST.
MaxPCASTSessions 8 # default value

# FileMCASTAddress <ipaddr> or <ipaddr:port>


# This is the multicast IP address used by the MCAST protocol when sending
# packets to clients
FileMCASTAddress 239.2.0.1:10000 # default value

# FileMCASTAddrCount <count>
# This is the size of multicast IP addresses pool used by MCAST. MCAST uses
# a new address for each file transfer
FileMCASTAddrCount 256 # default value

# FileMCASTEncrypt
# Include this option in the configuration file if you want to encrypt
# MCAST traffic. MCAST traffic is not encrypted by default.
# default: not included in the configuration

# FASTPort <port>
# FAST is the protocol used by Rembo clients to upload files on the server
# This option defines which UDP port to use when listening to client’s
# requests
FASTPort 4025 # default value

# FASTEncrypt
# FAST file transfers are not encrypted by default. Include this option in
# the configuration file if you want to encrypt FAST file transfers.
# default: not included in the configuration

#
# NBPServer
# ---------
#
# The NBP server is responsible for sending startup parameters to Rembo.
#

# NBPServerPort <port>
# This options modifies the port used by the NBP component of the Rembo
# server
NBPServerPort 4012 # default value

# DisableNBP

111
Appendix A. Sample configuration file
# Including this option in the configuration file causes the NBP component
# of the Rembo server to stop answering requests coming on the NBP port. Do
# not set this option if your server is used by Rembo clients
# default: not included in the configuration

#
# TCPServer
# ---------
#
# The TCP server is responsible for synchronization between servers and
# with RABAgent
#

# DisableTCP
# Include this option if you are not using server synchronization or if this
# server is not used as a RAB server. This will disable the TCP component of
# the Rembo server
# default: not included in the configuration

# TCPServerPort <port>
# This option defines the TCP port used by the TCP component of the Rembo
# server when listening to requests coming from other servers or RABAgent.
TCPServerPort 2048 #default value

112
Appendix B. Sample ISC DHCP 2.0 configuration file
#
# Sample configuration file for ISC DHCP 2.0 & Rembo
#

# Global options
use-host-decl-names on;

shared-network rembonet {

# Define your subnet here


subnet 192.168.1.0 netmask 255.255.255.0 {

# Define subnet specific options here (DNS server, ...)


#
option routers 192.168.1.1;

# Rembo hosts (dynamic or static) are grouped


# together because they share the same DHCP
# options
group {
default-lease-time -1;
# Define group specific options here (DNS server, ...)
#

# PXE specific option


# !! COMMENT THIS LINE IF THE REMBO SERVER
# !! AND THE DHCP SERVER ARE NOT ON THE SAME
# !! HOST
option dhcp-class-identifier "PXEClient";

# Fixed allocation (1 hardware address == 1 IP address)


host rembohst1 {
hardware ethernet 00:90:27:12:13:14;
fixed-address 192.168.1.20;
}
} # end of group
} # end of subnet

# Another subnet declaration. This subnet is used in


# dynamic allocation mode (pool of IP addresses)

subnet 172.20.0.0 netmask 255.255.0.0 {


option routers 172.20.1.1;

# Define more DHCP options here (DNS server, ...)

# PXE specific option


# !! COMMENT THIS LINE IF THE REMBO SERVER
# !! AND THE DHCP SERVER ARE NOT ON THE SAME
# !! HOST

113
Appendix B. Sample ISC DHCP 2.0 configuration file
option dhcp-class-identifier "PXEClient";

# Here we declare the range of IP addresses available for allocation


range 172.20.12.1 172.20.12.250;

} # end of subnet

114
Appendix C. Sample ISC DHCP 3.0 configuration file
# DHCP configuration file for DHCP ISC 3.0 & Rembo
#

# Global options
use-host-decl-names on;

# Subnet-specific options
subnet 192.168.1.0 netmask 255.255.255.0 {
option routers 192.168.1.1;

# Define subnet specific options here (DNS server, ...)


#

# Rembo hosts (dynamic or static) are grouped


# together because they share the same DHCP option
group {
default-lease-time -1;

# Define group specific options here (DNS server, ...)


#

# Option 43 telling that IP of Rembo server is C0:0A:0A:0A


# option vendor-encapsulated-options 06:01:07:08:07:00:0F:01:C0:0A:0A:0A:09:05

# PXE specific option


# !! COMMENT THIS LINE IF THE REMBO SERVER
# !! AND THE DHCP SERVER ARE NOT ON THE SAME
# !! HOST
option vendor-class-identifier "PXEClient";

# Fixed allocation (1 hardware address == 1 IP address)


host rembohst1 {
hardware ethernet 00:90:27:12:13:14;
fixed-address 192.168.1.20;
}
}
}

# Another subnet declaration.


# This subnet is used in dynamic allocation
# mode (pool of IP addresses)
subnet 172.20.0.0 netmask 255.255.0.0 {
option routers 172.20.1.1;

# Define more DHCP options here (DNS server, ...)

# PXE specific option


# !! COMMENT THIS LINE IF THE REMBO SERVER
# !! AND THE DHCP SERVER ARE NOT ON THE SAME
# !! HOST
option vendor-class-identifier "PXEClient";

115
Appendix C. Sample ISC DHCP 3.0 configuration file

# Here we declare the range of IP addresses available


# for allocation
range 172.20.12.1 172.20.12.250;
}

116
Server parameters functions Encrypt FAST datagrams
index FASTPort
Port used for FAST transfers
AuthDomain FileMCASTAddress
Authentication domain Multicast address used for the
AuthLocalDomain MCAST protocol
Local authentication domain FileMCASTEncrypt
AuthNTDomain
Encrypt MCAST datagrams
Remote NT authentication
FileMCASTTTL
domain
Time-To-Live used for
AuthRadiusDomain
MCAST datagrams
Radius authentication domain
FileServer
Backup
Define a new server for FILE
IP address of backup server
services
BaseDir
FileServerPort
Directory for all server files
Port used on the server for
BootDiscoveryAddress
NETfs, MCAST & FAST
Multicast address used for
requests
PXE discovery requests
Host
BootDiscoveryPort
Host entry in a host list
IP port used when listening to
PXE discovery requests HostRange
BootNoMulticastDiscovery Host range entry in a host list
Disable PXE multicast Interfaces
discovery support List of network interfaces
BootReplyDelay used by the server
Set the delay before answering Lockout
discovery requests Lock peripherals on the
DataDir remote client
Directory for internal files MaxLogSize
DisableBOOT Maximum size of log files
Disable PXE services created by the server
DisableDHCPProxy MaxPCASTSessions
Disable answers to DHCP Maximum number of
discovers (DHCPProxy) simultaneous PCAST sessions
DisableFILE MTFTPClients
Disable FILE (NetFS, The destination address and
MCAST) services port used by the MTFTP
DisableNBP server
Disable NBP services MTFTPMCastTTL
DisableTCP The TTL used for MTFTP
Disable TCP services multicast datagrams
FASTEncrypt MTFTPPort

117
Server parameters functions index
The port used by the MTFTP
server
MTFTPStartDelay
The initial delay on clients
before sending first MTFTP
request
NBPServerPort
Port used on the server for
NBP requests
NetPassword
Network password for remote
file access
Options
Startup options for the remote
client
PXEBootMode
Select PXE boot behaviour
RemoteConsole
Define a remote-console host
RemoteHost
Hostname or IP address of
remote TCP host
RemotePort
Numerical TCP port of remote
connection
SharedDir
Base directory for shared
repository
StartPage
REMBO
TCPServerPort
Define the TCP port used

118
REMBO Client Administration Manual
REMBO Client Administration Manual
Table of Contents
1. Getting Started with Rembo ............................................................................... 1
1.1. Starting REMBO for the first time.............................................................. 1
1.1.1. The appearance of REMBO............................................................. 1
1.1.2. Using Toolkit wizards ...................................................................... 2
1.1.3. Changing the startup page................................................................ 4
1.1.4. Showing REMBO console ............................................................... 4
1.2. Experimenting with REMBO scripts .......................................................... 5
1.2.1. Starting the interactive evaluator...................................................... 5
1.2.2. Experimenting basic functions......................................................... 5
1.2.3. Experimenting disk functions .......................................................... 5
2. Working with Rembo........................................................................................... 7
2.1. Accessing files under REMBO ................................................................... 7
2.2. Using REMBO variables ............................................................................ 8
2.2.1. Introduction...................................................................................... 8
2.2.2. Built-in variables.............................................................................. 9
2.2.2.1. Runtime built-in variables................................................... 12
2.2.3. Persistent variables......................................................................... 12
2.2.3.1. What persistent variables are useful for ? ........................... 12
2.2.3.2. How to create a persistent variable ..................................... 13
2.3. Disk image creation and restoration ......................................................... 13
2.3.1. How to create a disk image ............................................................ 14
2.3.2. How to restore a disk image........................................................... 14
2.3.3. Device specific archives................................................................. 16
2.3.4. Smart restoration: Synchronization................................................ 17
2.3.4.1. Synchronization: how it works ........................................... 17
2.3.4.2. Applications of the Synchronization method...................... 18
2.3.4.3. Synchronize syntax and usage ............................................ 18
2.4. Disk image format and the shared repository ........................................... 19
2.4.1. Image formats ................................................................................ 19
2.4.1.1. Sector-based cloning ........................................................... 19
2.4.1.2. Structure-based cloning ...................................................... 20
2.4.2. The shared repository..................................................................... 21
2.4.3. Moving shared files........................................................................ 22
2.4.4. Managing the shared repository..................................................... 22
2.5. Network protocols..................................................................................... 23
2.5.1. NETfs protocol............................................................................... 23
2.5.2. MCAST protocol ........................................................................... 23
2.5.3. PCAST protocol............................................................................. 25
2.5.4. FAST protocol................................................................................ 26
2.6. Advanced cloning topics........................................................................... 27
2.6.1. Filtering files with Virtual Images ................................................. 27

i
2.6.1.1. Creating the virtual image................................................... 28
2.6.1.2. Adding files or directories to a virtual image...................... 28
2.6.1.3. Removing files or directories from a virtual image ............ 28
2.6.1.4. Building a disk image from a virtual image........................ 28
2.6.1.5. Virtual images example....................................................... 29
2.6.2. Incremental images ........................................................................ 29
2.6.2.1. Basic incremental images ................................................... 29
2.6.2.2. Advanced incremental images ............................................ 30
2.6.2.3. How to create an incremental image................................... 31
2.6.3. Merging images using Virtual Images ........................................... 32
2.6.3.1. How to merge images together ?......................................... 32
2.6.4. Converting partition types.............................................................. 33
2.7. Starting REMBO without network connectivity....................................... 35
2.7.1. Off-line mode................................................................................. 35
2.7.1.1. Configuring Off-line mode ................................................. 35
2.7.1.2. How safe is off-line mode ? ................................................ 36
2.7.1.3. REMBO as a boot manager ................................................ 36
2.7.1.4. Off-line mode images ......................................................... 36
2.7.2. Booting REMBO from CD-Rom ................................................... 36
2.7.2.1. Generating a bootable CD-Rom.......................................... 37
2.7.3. Booting REMBO from a floppy..................................................... 37
2.7.4. Using PXE activation..................................................................... 37
2.8. Using TCP tunnels to access remote resources......................................... 38
2.8.1. Sending emails with REMBO........................................................ 39
2.8.2. Database access in REMBO .......................................................... 39
2.8.2.1. Gateway on Windows NT ................................................... 40
2.8.2.2. Gateway on Unix ................................................................ 40
2.8.2.3. Accessing from the client.................................................... 41
3. OS-Specific Instructions .................................................................................... 43
3.1. Cloning MS-DOS ..................................................................................... 43
3.1.1. Cloning a MS-DOS system............................................................ 43
3.1.2. Customizing a MS-DOS system .................................................... 43
3.1.3. Installing Lan Manager clients for UNDI...................................... 44
3.2. Cloning Windows 95/98/ME .................................................................... 45
3.2.1. Creating a Windows 9x base image ............................................... 45
3.2.2. Testing the base disk image ........................................................... 46
3.2.3. Create a restoration script .............................................................. 47
3.2.4. Synchronizing instead of RestoreDiskImage................................. 48
3.2.5. Customizing ................................................................................... 49
3.2.6. Basic incremental images .............................................................. 51
3.2.7. Advanced incremental images ....................................................... 52
3.2.7.1. Restoring an advanced incremental image.......................... 53
3.2.7.2. Going further....................................................................... 55

ii
3.3. Cloning Windows NT ............................................................................... 56
3.3.1. Creating a Windows NT base image.............................................. 56
3.3.2. Testing the base disk image ........................................................... 57
3.3.3. Create a restoration script .............................................................. 57
3.3.4. Synchronizing instead of RestoreDiskImage................................. 58
3.3.5. Customizing ................................................................................... 59
3.3.6. Incremental images (TextDiff)....................................................... 61
3.3.6.1. Restoring an incremental image.......................................... 62
3.3.7. Patching NT SID with REMBO .................................................... 62
3.4. Cloning Linux ........................................................................................... 64
3.4.1. Creating a Linux base image.......................................................... 64
3.4.2. Linux kernel booting...................................................................... 65
3.4.3. Testing the base disk image ........................................................... 66
3.4.4. Creating a restoration script ........................................................... 67
3.4.5. Linux Incremental images.............................................................. 68
3.4.6. Customizing Linux startup scripts ................................................. 68
I. REMBO URL types reference........................................................................... 70
Disk URLs ....................................................................................................... 72
Floppy URLs.................................................................................................... 75
CDROM URLs ................................................................................................ 77
Ramdisk URLs................................................................................................. 79
Net URLs ......................................................................................................... 81
Cache URLs ..................................................................................................... 85
Reg URLs......................................................................................................... 87
Arch URLs ....................................................................................................... 90
Diff URLs ........................................................................................................ 91
Link URLs ....................................................................................................... 93
Display URLs................................................................................................... 95
Loopback URLs ............................................................................................... 98
Variable URLs................................................................................................ 100
II. LicenseInfo built-in variable reference ......................................................... 102
LicenseInfo.EndUser ..................................................................................... 104
LicenseInfo.Reseller ...................................................................................... 105
LicenseInfo.Version ....................................................................................... 106
LicenseInfo.Build........................................................................................... 107
III. NetInfo built-in variable reference .............................................................. 108
NetInfo.MACAddress .................................................................................... 110
NetInfo.IPAddress.......................................................................................... 111
NetInfo.SubnetMask ...................................................................................... 112
NetInfo.DefaultGateway ................................................................................ 113
IV. HostInfo built-in variable reference............................................................. 114
HostInfo.RemboServer .................................................................................. 116

iii
HostInfo.RemboBackupServer ...................................................................... 117
HostInfo.FileServer........................................................................................ 118
HostInfo.FileBackupServer ........................................................................... 119
HostInfo.GroupName..................................................................................... 120
HostInfo.HostID............................................................................................. 121
HostInfo.StartPage ......................................................................................... 122
HostInfo.AdminMode.................................................................................... 123
V. SystemInfo built-in variable reference .......................................................... 124
SystemInfo.APM ........................................................................................... 126
SystemInfo.Disks ........................................................................................... 127
SystemInfo.Date............................................................................................. 128
SystemInfo.BootDevice ................................................................................. 129
VI. Settings built-in variable reference .............................................................. 130
Settings.ScreenSaverDelay ............................................................................ 132
Settings.MCASTSpeed .................................................................................. 133
Settings.MCASTSlowStart ............................................................................ 134
Settings.UseMCAST...................................................................................... 135
Settings.FASTSpeed ...................................................................................... 136
Settings.NetfsLatency .................................................................................... 138
Settings.ProgressBar ...................................................................................... 139
Settings.Compression .................................................................................... 140
Settings.VideoMode....................................................................................... 141
Settings.AllowScreenShots ............................................................................ 142
Settings.DefaultStyle ..................................................................................... 143
Settings.CachePath......................................................................................... 144
Settings.CachePartMD5................................................................................. 145
Settings.AutoPurge ........................................................................................ 146
Settings.AutoBoot.......................................................................................... 147
Settings.MaxFileSize ..................................................................................... 148
Settings.MaxCallDepth.................................................................................. 149
Settings.SharedPath ....................................................................................... 150
VII. AuthInfo built-in variable reference........................................................... 151
AuthInfo.Success ........................................................................................... 153
AuthInfo.UserName....................................................................................... 154
AuthInfo.Password......................................................................................... 155
AuthInfo.FullName........................................................................................ 156

iv
List of Tables
2-1. URL types defined in REMBO........................................................................... 8
2-2. Network protocols used by REMBO................................................................ 23
1. Supported registry types ...................................................................................... 87
List of Examples
2-1. Example ............................................................................................................ 14
2-2. Image restoration .............................................................................................. 15
2-3. Creating a virtual image ................................................................................... 28
2-4. How to create an incremental image ................................................................ 31
2-5. Restoring multiple image.................................................................................. 33
2-6. How restore an image on another type of partition .......................................... 34
3-1. Patching rembo.bat .......................................................................................... 43
3-2. Starting X based on the username .................................................................... 69

i
Chapter 1. Getting Started with Rembo

In this chapter, you will discover how REMBO works, what kind of tasks can be
performed and how to control the behavior of each client computer using REMBO.

1.1. Starting REMBO for the first time


First, configure a DHCP server and a REMBO server as described in the Server
administration manual. If your DHCP server and your REMBO server are properly
configured, REMBO will automatically start on any PXE-enabled computer on the
network. You will learn later on how to limit the hosts on which you want to start
REMBO. When REMBO takes control of the boot process, it first shortly displays a
few lines of informative text, starting with
Rembo - !PXE v1.1 API detected
IP:xx.xx.xx.xx Mask:xx.xx.xx.xx GW:xx.xx.xx.xx Server:xx.xx.xx.xx

After one second or so, REMBO switches to graphic mode and displays a welcome
page. At this point, REMBO is completely operational.

As REMBO provides tools to repartition and reformat your hard disk in a few
seconds, you face the risk of irremediably destroying the data stored on your
hard disk. Do never run REMBO on a computer with valuable data on the hard
disk, unless you know exactly what you are doing and you are confident
enough that your scripts will behave properly.

1.1.1. The appearance of REMBO


REMBO screen is divided into two parts: the desktop, and a tool bar at the bottom.
The content of the desktop is determined by an HTML page stored on the server. By
default, this file is named rembo.shtml, but you can setup a different file for
individual hosts or groups. You can freely customize the look of Rembo by editing
this file. The tool bar contains a menu on the left, which you can also customize.

During your exploration of REMBO, ensure that you are running REMBO in
Administrator mode: the toolbar menu should contain at least four items,
including one called Interact.... If it is not the case, you must activate the
administrator mode for this host. If you are using a Linux server, you can do
that by adding a line like
Options admin

at the beginning of the group definition in the rembo.conf file and send a kill
-HUP signal to the server. If you are running a Windows NT server, edit the

1
Chapter 1. Getting Started with Rembo
group definition using the Server Management Console and add the admin
option.

By default, REMBO starts the interactive wizards on startup. It displays host


information on the upper right corner of the screen, and six icons that let you
experiment with the main features of REMBO. Take some time to discover the
capabilities of REMBO, and interactively learn basic Rembo-C commands.

1.1.2. Using Toolkit wizards


When you start a REMBO client for the first time, you will notice six icons on a
black screen. These icons correspond to tasks that are available to you through
wizards. Wizards have been designed to help you perform basic deployment tasks
very easily, and to learn Rembo-C scripting language with examples.
Each icon corresponds to a different task. When clicking on an icon, you will see a
pop-up window with instructions on what information to enter to execute the chosen
command. Once the wizard is ready to execute the task, a window will be shown on
screen with the content of the Rembo-C script (a list of Rembo-C commands) that is
equivalent to the operation you are trying to perform. The script can be saved in a
directory on the server, thus allowing later re-execution of the same operation, or to
let you modify the script to create new operations based on the script generated by
the wizards.
Here are the main functions proposed by the wizards:

1. Computer settings. This wizard gives you the opportunity to change global
REMBO settings, like the screen resolution and the keyboard mapping to use.
The last item, startup script, lets you select which Rembo-C script to run when
computers start. By default, computers are configured to run the script called
wizard. The wizard script builds the wizards screen with the six icons on the
screen’s desktop. You can change the value of the startup script to one of the
scripts you have created with the wizards or manually. For example, if you
created a restoration script for a disk image you have created with the wizards,
setting the startup script to that restoration script will automatically instruct all
computers to run the restoration operation at next boot. Note that every
computer setting, like screen resolution and startup script, is stored in a
persistent variable on the server. You can modify the values with this wizard,
but also with the Server Console by editing the corresponding persistent
variable. You can also override a persistent variable at a host level (i.e. set a
different startup script just for one host) using the Server Console.
2. FDisk (partition manager). This wizard is a partition management tool. It
supports creating a new partition, deleting a partition, formatting a newly

2
Chapter 1. Getting Started with Rembo
created partition, and browsing the content of a partition. This tool is very
useful on computers with no operating system installed: just boot on the
network, and use REMBO to configure the partitions before starting the
operating system installation.
3. Floppy-disk imaging. This wizard creates and restores the content of a
floppy-disk. You can create an image of any kind of floppy disk. If the floppy
disk contains a valid filesystem (i.e. FAT), then you can create a shared image
(archive using the shared repository on the server), or a monolithic image
(archive with its own content). If the floppy does not contain a valid filesystem
(i.e. linux kernel floppy), then it is better to create a raw, or sector-by-sector
image of your floppy. Floppy images are stored on the server, and can be used
on any REMBO computer, either as ramdisks, or to create a new floppy. When
using an image in a ramdisk, the content of the floppy is restored in a ramdisk,
and REMBO boots on that ramdisk. If the ramdisk is bootable (i.e. the floppy
used to create the image is bootable), then you will get the same result as if you
had inserted the floppy in the computer, without having to physically insert the
floppy.
4. Execute a script. Use this icon to run scripts that you have created manually or
scripts generated by other wizards icons. For example, if you have created an
image of your hard-disk, and you want to restore this image (i.e. deploy) on a
different computer, simply choose the restoration script corresponding to the
image you created. A window containing the script will show up, and you will
be able to modify parameters in the script, like the hostname to use when
restoring the image.
5. OS creation. This icon is the most powerful of the six icons. It gives you a list
of operating systems installed on your computer, with the option of creating an
image of the operating system of your choice. When the image is created and
stored on the REMBO server, a deployment script is created on the server. This
deployment script can be executed to deploy the operating system on a different
computer, using the same partitioning scheme as the original computer. It is
highly recommended to have a look at the restoration script to see what
Rembo-C commands are used to partition a disk, restore an image, change the
hostname of the computer, and boot on the hard-disk.
6. Software snapshot. Along with the OS creation icon, this icon is the one you
will find the most interesting. This icon guides you through the process of
creating an image of an operating system application, and it also generates a
script that you can later use in conjunction with an image restoration script to
restore both an operating system and applications. This gives you the ability to
combine operating systems and applications on-demand, simply by combining
software snapshots scripts with image restoration scripts. If you look at an
image restoration script (that has been created with the OS creation icon), you
will see a place with a comment saying INSERT SOFTWARE SNAPSHOTS

3
Chapter 1. Getting Started with Rembo
HERE. Simply add a line for executing your software snapshots scripts at that
location in the global restoration script and you will have a script that combines
both operating system restoration and software snapshot restoration.

REMBO Toolkit wizards have been designed to show you what Rembo-C
commands to type to create and restore REMBO objects, like floppy images,
hard-disk images, and application images. We recommend you to use the wizards to
generate scripts, and then use your favorite text editor to edit scripts on the
server-side (in files/global/scripts on your server). The goal of the wizards is
to help you create your own scripts by combining scripts generated by wizards
icons, and adding your own commands or function to further customize scripts. For
example, you can use the DHCPRequestInfo function to retrieve DHCP information
on the host REMBO is running on, and then use the DHCP hostname to customize
the operating system that you are restoring in your script.
The sections below show you how to modify REMBO startup page, and how to
write your own REMBO scripts. Use the information written in these sections when
you are already familiar with the wizards, in order to go further than simple
Rembo-C scripting.

1.1.3. Changing the startup page


You have several possibilities for editing the desktop HTML page:

• Editing it on the server using the server management console (the console is
running under Windows only).
• Editing it directly on the server. The startup page is located in the folder
files/global relative to the folder where you have installed REMBO server.

Take a few minutes to see how this page is defined. Note the use of scripts to
perform actions (like hiding the console window, which is in this case useless since
the console is already hidden), the possible definition of CSS1-like stylesheets, and
the inclusion PCX images. You can try to change the file, save it and see how your
changes affect the look of REMBO.

1.1.4. Showing REMBO console


If you make errors in your scripts for instance, you may want to check the local
console for a detailed report or other informative messages. To do so, simply use the
Show console option in the toolbar menu. This will open a wide window, with a log
of all events of interest. You can also read from there whether REMBO is running in
administrator mode or not, as well as the amount of memory detected by REMBO.

4
Chapter 1. Getting Started with Rembo
To hide the console again, just click on the round button on the upper right corner of
the window.
You can try to make the console window pop-up by itself by editing the script in
rembo.shtml and replace the HideConsole() by ShowConsole().

1.2. Experimenting with REMBO scripts


REMBO interactive mode allows you to evaluate simple script expressions one by
one, and to see the results immediately in the console window. This mode is very
useful for testing individual commands to be later inserted in REMBO scripts.

1.2.1. Starting the interactive evaluator


The interactive evalator is available from the Start menu when the client is
configured in Administrator mode. Refer to the previous note for instructions on
how to setup the administrator mode.

1.2.2. Experimenting basic functions


With the REMBO console visible, try to evaluate the following commands:

• Log("Hello <I>world</I>"); This should simply print the string between quotes
on the console. Note that the command you evaluated is written in green before it
is executed. Also note that as the display is HTML-aware, the word world comes
out in italics.
• Keyb("fr"); This command loads a national keyboard mapping (see the
reference manual page for the list of country codes) so that you can do your tests
without having to guess where keys are on a US keyboard. Note that this
command is typically inserted in the script section of rembo.shtml.
• Log(GetPrimaryPartitions(0)); This command will show the content of the first
partition table of your first hard disk.
• str part = GetPrimaryPartitions(0); This is similar, but instead of displaying
the result, it is stored in a variable named part. See Section 2.2 for a discussion
about variables.
• PowerOff(); If your computer is APM compliant, you should quickly understand
what this command does...

5
Chapter 1. Getting Started with Rembo
1.2.3. Experimenting disk functions

Caution! The commands listed below will sweep away the content of the hard
disk of the computer on which you run them. Never use them on a computer
with valuable data on the hard disk.

• SetPrimaryPartitions(0,"FAT16:200000"); This command will change the


partition table (like the usual fdisk program) and create a single FAT-16 partition
of 200 MB. This function only changes the partition table. It does not format the
partitions themselves.
• HDClean(0,0); This command cleans up the master boot record (MBR) of the
first hard disk.
• HDClean(0,1); This command quick-formats the partition 1 of the first hard
disk. If you typed the SetPartition command above, this will prepare the
partition with an empty FAT-16 filesystem.
• CreateTextFile("disk://0:1/greetings.txt","From Rembo"); This command
creates a text file named greetings.txt in the root directory of the newly
formatted FAT-16 partition. The file name is given as an URL. See Section 2.1 for
a description of URLs recognized by REMBO.
• CreateDir("disk://0:1/temp"); This command creates a new directory named
temp.

• FloppyBoot(); Let the computer boot from a floppy disk, for instance to install
an operating system manually or to verify that REMBO has really done what he
was supposed to do.

Of course, the goal of REMBO is not to reformat the hard disk and to reinstall an
operating system manually. You will learn in Section 2.3 how to use disk imaging to
automatically install an operating system on a computer, and how to automatically
configure it.
The next chapter will move on to writing real scripts to customize the behavior of
your remote-boot workstations.

6
Chapter 2. Working with Rembo

This chapter explains various topics that will help you understand how to customize
the behavior of REMBO to fit your needs, by writing your own REMBO scripts.
This chapter is a very important complement to the Rembo-C programming manual.

2.1. Accessing files under REMBO


All files and directories are identified with Uniform Resources Locators, or URL for
short. A URL is like a path, except that it adds two fields aside the path itself. These
two fields allow the resource (the file or directory) to be globally located.
Strictly speaking, a REMBO URL is made of three fields:

The URL type, or prefix:


The URL type determines the method used to find the specified resources.

In http://www.rembo.com/index.html, the URL type is http, a protocol used


to retrieve files over the internet.

The root device:


The root device identifies the device, host or domain where the resources is
stored.

In http://www.rembo.com/index.html, the root device is www.rembo.com.


This is the host name of the computer where REMBO Technology’s pages are
stored.

The pathname:
The path name is the actual location of the file on the device specified by the
root device part of the URL.

In http://www.rembo.com/rembo/index.html, the pathname is


/rembo/index.html. It means that the file described by this URL is named
rembo.html and is located in the directory rembo.

7
Chapter 2. Working with Rembo

Table 2-1 describes the nine URL types supported by REMBO. These URL types
are defined in detail in the next sections of this chapter.
Table 2-1. URL types defined in REMBO

disk Local hard disk


floppy Local floppy disk
cdrom CD-Rom disk
ram REMBO ram disks
net Remote file, accessed through NETfs
cache Remote file, accessed through the local
cache partition
reg Windows NT registry
arch REMBO disk image archive (read-only)
diff REMBO differential image archive
(read-only)
link REMBO virtual filesystem
display REMBO user interface
loop Loopback devices
var REMBO memory-mapped files

Each URL type is described by a manual page in the reference part of this
document.

2.2. Using REMBO variables

2.2.1. Introduction
As any other programming language, Rembo-C offers variable to store information
for later usage. Rembo-C variables need to be declared (i.e. the first invocation of
the variable must tell which variable type to use), but the declaration can occur
anywhere in the Rembo-C program.
There are several kind of variables in REMBO; you can select the kind of variable
satisfying your requirements in the following list:

• Built-in variables: these variables always exist, and exist everywhere. A default
value is assigned to each built-in variable by REMBO on startup. An example of
built-in variable is NetInfo.IPAddress, a variable containing the IP address of
the REMBO host;
• Global variables: global variables are created by Rembo-C scripts, outside a
function declaration. Global variables are accessible from anywhere (any script,

8
Chapter 2. Working with Rembo
any thread), just like built-in variables. When you create a new Rembo-C
function, its content is stored in a global variable with the same name as your
function. Unless exported as a persistent variable (see below), global variables
are discarded when REMBO starts the operating system or reboots;
• Local variables: local variables are created inside functions, or more generally,
inside a Rembo-C code block (you can create a local variable inside a for loop
for example). Local variables are accessible in the scope where they have been
created only (i.e. limited to the Rembo-C code block containing the variable).
When a local variable is no more referenced, for example when the function it
has been created in is finished, the REMBO garbage collector discards the local
variable;
• Persistent variables: a persistent variable is a status added to a built-in, global or
local variable content. If the content of a variable is made persistent with the
Export function, the variable will be automatically recreated on next boot during
REMBO initialization. See Section 2.2.3.

A built-in, global or local variable can have a simple (scalar) or complex type. The
following types are supported:

• int varname: an 32 bits signed integer value;


• bool varname: a boolean (valid values: true or false);
• str varname: a REMBO string. Strings can be concatened with the + operator,
and individual characters can be selected by using the string variable as an array
(varname[0] will return a string containing the first character of the string
variable varname);
• var varname: a complex REMBO variable. This type of variable stores a
reference to a complex variable, such an array, a structure, an enumeration or a
binary buffer;
• xxx varname[]: an array of elements of type xxx (xxx can be either int, str,
bool or var). Arrays can be combined to create multi dimensional arrays.

See Section 2.2 in Rembo-C Scripting Reference Manual for more information on
arrays, structures and enumerations.

2.2.2. Built-in variables


Several variables are created by REMBO and are available for use within your
REMBO scripts.
These built-in variables are stored in seven global structures:

9
Chapter 2. Working with Rembo
• LicenseInfo, containing information about the REMBO version number and the
customer name;
• NetInfo, containing information about the network interface configuration;
• HostInfo, containing information about the host configuration parameters
(server parameters defined for this host);
• SystemInfo, containing information about the system (hardware information);
• Settings, containing variables that can be modified to change the behaviour of
REMBO
• AuthInfo, containing information about the last authenticated user (see
AuthUser in the programmer’s manual);
• DHCPInfo, containing information about the the last DHCP packet received
through the function RequestDHCPInfo.

Here is the list of all built-in variables, organized in the seven global structures.
Each variable is described in detail in the reference section at the end of this
document.

• LicenseInfo.EndUser: the name of the end user REMBO is licensed to;


• LicenseInfo.Reseller: if REMBO has been purchased through a reseller, this
variable contains the name of the reseller;
• LicenseInfo.Version: REMBO version (e.g. "1.0");
• LicenseInfo.Build: REMBO build number (e.g. "002");
• NetInfo.MACAddress: the hardware address of the network interface;
• NetInfo.IPAddress: the IP address of the network interface;
• NetInfo.SubnetMask: the subnet mask of the network interface;
• NetInfo.DefaultGateway: the IP address of the default gateway (i.e. the router);
• HostInfo.RemboServer: the IP address of the REMBO server;
• HostInfo.RemboBackupServer: the IP address of the REMBO backup server;
• HostInfo.FileServer: the IP address of the REMBO file server;
• HostInfo.FileBackupServer: the IP address of the REMBO file backup server;
• HostInfo.GroupName: the name of the group this host is in;
• HostInfo.HostID: the host identifier used to build net://host URLs (usually
the hardware address without spaces);

10
Chapter 2. Working with Rembo
• HostInfo.StartPage: the filename of the HTML page loaded on startup, as set
in the server configuration;
• HostInfo.AdminMode: true if administrator mode is enabled for this host in the
server configuration;
• SystemInfo.APM: true if Advanced Power Management is supported (i.e. soft
power-off);
• SystemInfo.Disks: an array containing information about detected hard disks;
• SystemInfo.Date: the current system date;
• SystemInfo.BootDevice: the device used during the boot;
• Settings.ScreenSaverDelay: the delay used by the screen saver (0 means no
screen saver);
• Settings.MCASTSpeed: multicast bandwidth limitation factor (0 means no
limitation);
• Settings.MCASTSlowStart: true if multicast slow start is enabled;
• Settings.UseMCAST: true if multicast is used for file downloads to the local
cache partition;
• Settings.NetfsLatency: network filesystem cache latency, in hundredths of a
second;
• Settings.ProgressBar: if false, progress bars are not displayed;
• Settings.Compression: compression level used to compress hard disk images
(0-9, default is 5);
• Settings.VideoMode: the current video mode;
• Settings.AllowScreenShots: true if the PrintScreen functions are enabled;
• Settings.DefaultStyle: the default CSS style sheet;
• Settings.CachePath: path to the local cache partition (default is disk://0:-1);
• Settings.CachePartMD5: if true, each block read in the cache partition is
checked for consistency against a MD5 file downloaded from the server;
• Settings.AutoPurge: if true, the cache partition automatically purges the least
recently used file when free space is needed to cache a server file;
• Settings.AutoBoot: true if reboot on fatal error is activated;
• Settings.MaxFileSize: the maximal file size used by REMBO;
• Settings.MaxCallDepth: the maximum level of recursion allowed for Rembo-C
functions;
• Settings.SharedPath: shared repository path (default is /shared);

11
Chapter 2. Working with Rembo
• AuthInfo.Success: true if last authentication attempt was successful. Other
AuthInfo fields are only valid if this variable is set to true;

• AuthInfo.UserName: the username of last authenticated user;


• AuthInfo.Password: the password of last authenticated user;
• AuthInfo.FullName: the full name (if available) of last authenticated user;
• DHCPInfo.TimeStamp: the date of the last received DHCP reply. Other DHCPInfo
are set from the content of the DHCP reply packet.

2.2.2.1. Runtime built-in variables


Run-time built-in variables are not created automatically by REMBO, but are
created when executing specific functions. For example, the RequestDHCPInfo
requests DHCP information from a DHCP server and sets the DHCPInfo structure
with variables corresponding to the content of the reply packet. You can use
LogVar(DHCPInfo); to list all DHCP-related variables.

2.2.3. Persistent variables


When you create a variable in one of your scripts, this variable only exists during
the current session, because it is stored in the memory of the computer. When the
computer reboots and REMBO is called again, the content of the variable is lost.
Persistent variables are just like others variables, but they persist through computer
reboots. Once a variable has been created and declared as persistent, its value will be
available during the current session and successive session. This is possible because
persistent variables are stored on the server instead of the local computer memory.
When REMBO starts, it tries to load and execute a file called autoload on the
server. This file contains statements used to declare persistent variables created
during previous sessions. A persistent variable is actually a statement stored in the
autoload file on the server. Each time you modify a persistent variable, you must
update its declaration in the autoload.
The file autoload is fetched from four different locations on the server by the
REMBO client: net://global/autoload, net://group/autoload,
net://host/autoload and net://user/autoload (when the user is authenticated).
These file are executed in the global - group - host - user order. That means
that if a persistent variable is declared in both the net://global/autoload and the
net://group/autoload, the declaration in the group will overwrite the global
declaration: the most specific declaration will always replace the more generic
declarations.

12
Chapter 2. Working with Rembo
2.2.3.1. What persistent variables are useful for ?
You can use persistent variables to store settings, computer states or user profiles.
For example, you can store the last choice of the user in the net://user/autoload
file, and use this choice to present a default choice to the user on next boot.
A persistent variable could also be used as a temporary setting modifying the
behaviour of REMBO. You can write your default script such as if the variable
win2k is set, a Windows 2000 is proposed to the user.

Another use of a persistent variable is in disk restoration scripts. A persistent


variable can be set just before the restoration begins, and unset when the restoration
completed successfully. Then, if the variable is set on the next boot, that means that
something went wrong during the last boot and special tasks must be performed,
such as disk cleaning.

2.2.3.2. How to create a persistent variable


On the REMBO client: use the Export function to transform an existing variable in
a persistent variable. You must specify the variable, a name for this variable on next
boots (we recommend you to use the same name as the current name of the
variable) and the scope in which the variable must be declared (global, group, host
or user -- you can use the user scope only when a user is validated). You must call
this function when you first transform a normal variable in a persistent variable, and
each time you modify the persistent variable (in order to update the declaration
stored on the server). Use the UnExport function to remove a persistent variable
declaration.
On the REMBO server, you can create, modify or delete a persistent variable by
editing the corresponding autoload. The net URL manual page contains
information on how to find files stored in group, host and user scopes.
The Server Console application provides a convenient graphical interface for
modifying persistent variables. This feature is supported for Unix REMBO server
as well (i.e. you can edit persistent variables on a Unix REMBO server from the
Windows Server Console).

When modifying a autoload by hand, use correctly formed REMBO script


statements. If there is a parsing error in one of the autoload files, the error will
be displayed when the computer starts, and the execution will be stopped.

2.3. Disk image creation and restoration


Disk image creation/restoration is a central feature of REMBO software. It allows
for operating system cloning in a very efficient way. REMBO is able to clone the

13
Chapter 2. Working with Rembo
following operating systems:

• MS-DOS
• Windows 95, Windows 98 and Windows ME
• Windows NT 4.0, Windows 2000 and Windows XP
• Linux

The REMBO Toolkit built-in wizards will help you clone these operating systems
without much difficulties, and will show you the corresponding Rembo-C code. The
following sections will give you more explanations on the underlying process, to
help you understand it and modify it according to your needs. If you want to learn
more about the format of disk images, see the next section (Section 2.4.1).

2.3.1. How to create a disk image


The first step of the cloning process is creating an image of one of the reference
computer’s hard disk partitions. This image will then be used to clone this reference
computer to several other computers.
The function involved in the disk image creation process is BuildDiskImage. The
first two parameters of BuildDiskImage are used to specify the hard disk partition
to backup, while the third parameter is the name of the file which will be used by
REMBO to store the disk image.

Disk images filenames must begin with cache: or net: because the disk image
creation process involves a phase performed on the server. If you want to
store the disk image in a different location, you must first create the image on a
REMBO server (with a net: or cache: filename) and then copy the image from
the server to the final image destination.
Example 2-1. Example

To create an image of the first partition stored on the first hard disk, and to store the
result in the file winxp on the local server, type
BuildDiskImage(0,1,"cache://global/winxp");
. Once the image is created, you can download the image in your local cache
partition and look at its content with the following commands sequence:
OpenArchive("testarch","cache://global/winxp");
FileMan("arch://testarch/");

Use CloseArchive to close the archive opened with OpenArchive and release
system resources.

14
Chapter 2. Working with Rembo
2.3.2. How to restore a disk image
The disk images created with REMBO can be later restored on one or several
clients with the RestoreDiskImage function. This function takes three parameters:
the hard disk and partition number to restore to and the filename containing the disk
image to be restored.
Here are some considerations about disk restoration:

• Create partitions before restoring the disk image. Use a partition type that is
compatible with the data stored in the disk image. For example, do not restore an
EXT2 (Linux) disk image on a FAT16 partition (although REMBO will be able to
restore the files, the result will probably not be what you originally wanted).
• Always setup a cache partition on your target computers and use a cache: URL
to specify the filename containing the disk image. This will greatly improves
performance since it will ask REMBO to cache a copy of the disk image on the
local disk, and this copy will be downloaded with the very efficient multicast
protocol (allowing multiple clients to download the same file at the same time)
instead of the slower net: protocol (net: is not intended for large files).
You can setup a cache partition by leaving unpartitioned disk space at the end of
your first hard disk. REMBO will automatically detect this unpartitioned space
and will use it for caching network file accessed through cache: URLs. The
cache partition is invisible to operating systems, because it is outside any
allocated (partitioned) area. However, its data will be preserved as any other area
of the disk. If any corruption occurs, it will be automatically detected by REMBO
and instantly fixed.

• If the target partition is not empty, you can use HDClean to clean the partition
before restoring files on it. If you try to restore a disk image on a partition that
contains files, REMBO will switch to the Synchronize mode and will try to
restore the modified files only. If you are sure that you want to destroy all the data
present on the target partition, use HDClean so that it will be faster. Note that
RestoreDiskImage includes a call to HDClean and will therefore always clean the
partition before restoring the image.

Example 2-2. Image restoration

This example shows the sequence of REMBO script commands needed to prepare
the target partition and to restore a disk image created with BuildDiskImage. In this
example, the disk image will be restored on the first partition of the first hard disk.
The size of the hard disk is 20Gb, and we want to keep 1500Mb for the cache
partition.

15
Chapter 2. Working with Rembo
We first create the partitions with the SetPrimaryPartitions function. We want
18.5Gb for a NTFS partition, and 1500Mb for the cache partition:
SetPrimaryPartitions(0,"NTFS:18500000");. Note that the cache
partition is not specified in the call to SetPrimaryPartitions since the cache
partition is the unpartitioned space at the end of the hard disk.
Finally, we restore the disk image with the RestoreDiskImage function:
RestoreDiskImage(0,1,"cache://global/winxp");. Note that the
RestoreDiskImage performs a quick-format on the target partition before restoring
the image.
In summary:
SetPrimaryPartitions(0,"NTFS:18500000");
RestoreDiskImage(0,1,"cache://global/winxp");
/* To boot the resulting disk image: */
HDBoot(0,1);

Additionally, you can open a file manager on the target partition to verify that all the
data have been properly written: FileMan("disk://0:1/");. Or you can
boot on the newly created partition with HDBoot(0,1);.

2.3.3. Device specific archives


In order to be able to preserve most of the filesystem structure (i.e. file numbering,
file compression, cluster size, ...) when backing up and restoring a disk partition,
NTFS disk archives have become device specific. That means that an archive of an
NTFS filesystem created on a Windows 2000 partition can only be restored on a
Windows 2000 partition. This ensures that NTFS system or compressed files
contained in the archive will be recreated with the same format as in the original
partition that was used to create the archive.
In order to create a partition that is compatible with the filesystem contained in a
disk archive (e.g. Windows XP NTFS), the function DeviceCleanEx must be used
instead of HDClean. This extended version of the formatting function allows for an
additional parameter specifying device parameters to use to create the partition, as
the cluster size or the total number of files. The function DeviceGetInfo retrieves
this device information block from either a disk archive or a disk partition.
As an example, let us say that the first primary partition has been formatted in
NTFS under Windows XP, and the second primary partition need to be formatted
with the same format. The following command would format the second partition
using device information taken from the first partition:
var devinfo = DeviceGetInfo("disk://0:1");
DeviceCleanEx("disk://0:2",devinfo);

16
Chapter 2. Working with Rembo

As a second example, let us consider the case of a disk archive created on a


Windows 2000 NTFS partition containing compressed files. To restore this archive,
the destination partition must be formatted with the same device parameters as the
original partition. The device information block is taken from the archive and then
used to format the target partition.
var devinfo = DeviceGetInfo("cache://global/archive.img");
DeviceCleanEx("disk://0:1",devinfo);

2.3.4. Smart restoration: Synchronization


Most cloning techniques available today are used to install a new operating system
on an empty workstation (OS deployment). REMBO goes a step further with its
synchronization mode, where disk cloning is not anymore limited to OS
deployment applications.

2.3.4.1. Synchronization: how it works


Instead of blindly restoring the disk image by destroying all the data previously
stored on the target partition, REMBO can selectively restore files based on several
rules:

• In default mode, the synchronize process will restore only files for which filesize,
dates or attributes have changed. This is similar to a standard backup/restore tool.
• In secure mode, the synchronize process will restore all the files which contents
has changed. REMBO computes MD5 hash digest on files to determine if a file
has changed. This is a very secure way to make sure that the file will be copied
even if a malicious user has reset the dates and attribute of the file to original
values.
• In compatible mode, the synchronize process will restore all the files, thus
emulating a standard cloning tool.

Additionally, synchronize can work in one of the three following modes when
deciding what to do with new files (files present in the disk image but no on the
target partition) and old files (files present on the target partition but not in the disk
image):

• In compare mode, the synchronize process will not add new files to the target
partition nor delete files from it. REMBO will only update files existing in both
the disk image and the target partition.

17
Chapter 2. Working with Rembo
• In add mode, the synchronize process will add new files to the target partition
but will not delete old files. This is very useful to bring a used workstation in a
safe state: all OS files will be restored to their original content, but other files
installed by the user will stay untouched.
• In full mode, the synchronize process will add new files to the target partition
and delete old files. In this mode, the target partition will be an exact copy of the
disk image at the end of the restoration process. This is the default mode.

2.3.4.2. Applications of the Synchronization method


Here is a list of environement in which the Synchronization may be more useful
than a simple cloning tool:

• Schools. Schools and universities have a requirement for strong security


concerning student workstations. This security is usually achieved by restoring
the full operating system at each boot. In this case, the Synchronize method in
full/dates mode brings a real performance improvement by restoring only
modified files. On a typical student workstations, a few dozens of files are
modified from one boot to the other. The Synchronize process is able to scan the
target partition and restore these changed files in a few seconds.
• Internet cafés. Internet cafés, like schools, require a high level of security. The
Synchronize method greatly improves performance if the restore-at-each-boot
solution is choosed to achieve the required security level.
• Large companies helpdesk. Synchronize in add/dates mode can be used by help
desks to bring a corrupted computer to a safe state remotely. Since REMBO is
able to work even when the installed operating system is corrupted, it is always
possible to restore system files and therefore fix corruption problems. If used in
add mode, synchronize will not delete existing files, such as user personal files or
installed software. However, it is recommended to create a separate partition for
user files, or better, ask users to store their files on servers only, so that complete
hard disk restoration is possible in case of severe operating system corruption.

2.3.4.3. Synchronize syntax and usage


The complete syntax for the Synchronize function can be found on the
Synchronize manual page.

Note that BuildDiskImage and RestoreDiskImage are aliases to the


Synchronize: BuildDiskImage(0,1,"cache://global/test"); is

18
Chapter 2. Working with Rembo
equivalent to
Synchronize("disk://0:1/","cache://global/test","");
And RestoreDiskImage(0,1,"cache://global/test"); is
equivalent to
DeviceCleanEx("disk://0:1",DeviceGetInfo("cache://global/test"));
Synchronize("cache://global/test","disk://0:1/","b");

2.4. Disk image format and the shared repository


This section provides some details on the way REMBO images are stored, and
specifically on the implecations of the shared repository mechanism.

2.4.1. Image formats


Cloning is the process of duplicating an installed operating system from one
reference computer to one or more other computers. This is done by backuping all
the data stored on the partitions of the reference computer and restoring these data
on the target computers. In this documentation, the data extracted from the
reference computer is called a disk image. Disk images are usually stored in a file
on a server (image archive), so that it can be restored on target computers without
needing to have the reference computer powered on.
There are two known methods for cloning disk partitions, sector-based or
structure-based cloning. The sector-based method can be furthermore divided in
two categories: blind analysis or allocation-aware analysis. These methods are
briefly discussed below.
Note: Rembo uses a structure-based cloning method.

2.4.1.1. Sector-based cloning


This is the simplest method of cloning. Individual sectors (sequential data units of
the disk) are backuped in an archive, and then restored on the target computer. The
cloning tool has no knowledge of the underlying filesystem structure. This kind of
method has the advantage of supporting virtually all existing operating systems,
since it does not care about the contents of the hard disk. The first disadvantage of
this method is that the target partition must have the same size as the reference
partition since filesystem structures are copied as-is, with all information about the
size of the filesystem transferred unmodified. The second disadvantage is that free
space is cloned (this method does not know if a particular data unit is in use or not).
If the reference partition uses only 10% of the total disk space, then only 10% of the

19
Chapter 2. Working with Rembo
resulting disk image will be relevant. Since smaller disk images means faster
network transfers and faster restoration, it is obvious that this is a real disadvantage.
Allocation-aware cloning is an evolution of the blind method described in the above
paragraph, designed to solve the two main disadvantages of sector-based cloning
techniques. An allocation-aware cloning method has a limited knowledge of the
allocation mechanisms used by the underlying filesystem structure. This knowledge
allows the allocation-aware method to skip unused data units and store only relevant
information in the disk image. Additionally, some of these allocation-aware cloning
tools are also able to restore a disk image on a partition which size is different from
the size of the reference partition. This is done by modifying limited parts of the
underlying filesystem structure. This method is an evolution of the blind method in
that it solves the two main disadvantages of the blind method, but it also introduces
a new disadvantage. The allocation-aware method must be able to understand and
modify the internal structures used by the filesystem installed on the reference
partition. Consequently, this method will only work for the list of filesystems
supported by the cloning tool.

2.4.1.2. Structure-based cloning


Structure-based cloning is the opposite of sector-based cloning, because it requires
an extensive knowledge of the filesystem installed on the reference computer, and
the capability to rebuild a complete filesystem on the target computer.
Structure-based cloning methods work with files and directory rather than sectors,
just like a backup/restore utility. Here are the advantages of structure-based cloning:

• More flexible than sector-based cloning. The cloning tool can select which files
to backup or restore (or which files not to backup, for example the virtual
memory paging file).
• Can restore files on an existing filesystem. Existing files will not be discarded.
• Disk images can be edited to remove unwanted files or directories at the
restoration stage (disk images are like a filesystem).
• Can synchronize rather than clone: files already installed on the target computer
and identical to the reference files will not be restored. This can be used to bring
an existing computer in the same state as the reference computer without
discarding the operating system settings.

Since release 2.0 of REMBO Toolkit, disk images can benefit of a new evolution of
structure-based cloning: shared file storage. The principle is that the disk image
only contains the description of the whole structure and content of the hard-disk,
but that the actual content is stored separately, in a shared repository, so that if the

20
Chapter 2. Working with Rembo
same file is used in two different images, it is stored only once. This new technique
has numerous advantages:

• It reduces the storage requirements on the server by an order of magnitude.


• It makes it possible to keep several operating system images on the client cache
partition, without significant additional disk space consumption.
• It accelerates the image creation process by an order of magnitude starting with
the 2nd image of any operating system, since only a fraction of the files will have
to be uploaded. Note however that the first image creation is likely to take up two
twice longer, due to the indexation process.
• It accelerates the download multiple images on a client, since files present in
several images will only be downloaded once.
• It makes the simultaneous download of images for several hardware platforms
much more scalable, since most of the files will be in common even for different
hardware.
• It makes it possible to upgrade disk images on a remote server much more
efficiently (in a server replication scenario for instance), since the whole new
image will not have to be completely uploaded, but only the new files.

If needed for special applications, it is still possible to create monolithic


REMBO images, similar to the ones created with release 1.x of the Toolkit.
See the documentation of the Synchronize for more details.

2.4.2. The shared repository


The shared repository is a huge content-indexed dictionary of files. Every file is
individually stored, indexed by a global MD5 and a subsidiary list of MD5s for each
32KB block. In the REMBO disk image, the file content is not stored, but only the
list of MD5s. When reading from an archive, the actual content is automatically
taken from the shared repository.
There is typically one shared repository on each device on which there is a REMBO
archives, but this is not a rule. The path used as shared repository is defined by the
predefined variable Settings.SharedPath, which defaults to /shared (e.g. the
directory shared at the root of the device where the archive is found). You may
specify a device-absolute path such as cdrom://0:0/shared to force the use of a
shared repository in a given location, use a completely relative path such as shared
to look in the directory directly next to the archive.

21
Chapter 2. Working with Rembo
For the sake of efficiency, shared files are not stored individually but are embedded
in common pool files, that are better cached by the system. There are also some
index files, that allow to quickly locate a file given its MD5 description. Note that
all these files can safely be backed up at any time, since once a content-indexed file
is added, it never changes its location in the index and the consistency is therefore
guaranteed at any time (this is by definition in a content-indexed repository: when a
file file has changed, it is considered as a different file, since it has a different MD5
index).

2.4.3. Moving shared files


The only complexity introduced by the use of the shared repository is to ensure that
the required shared files are moved along with the archive when transfering it from
one device to the other, or over the network. In particular, the implicit mechanism
that downloads files to the cache partition when using cache:// URLs does not
automatically copy related shared files to the cache partition. This has to be done
explicitely using the CopyCache function, before using OpenArchive for instance.
To easily handle the most frequent case, that is, cloning from a cache:// URL to
the disk using Synchronize or RestoreDiskImage, an implicit call to CopyCache
has been added into the Synchronize. However, if you intend to restore several
archives, it is nicer to explicitely use CopyCache on all archives at once, in order to
have one single progress bar for all downloads.
If you want to move several files (including archives) from one device to the other,
possibly to or from the network, but not necessarily using the cache partition, you
should use the BatchTransfer function. This function will perform a copy of
multiple files in the most efficient way, copying required shared files, and with a
global progress bar. In addition, if the source is a removable media such as a
CD-ROM or DVD-ROM, media spanning is transparently supported.

For information on how to perform similar operations from a command-line (on


the server), see the Chapter 3 in REMBO Server Administration Manual.

2.4.4. Managing the shared repository


During a regular use, the shared repository normally only grows as new files are
added. If for some reason you want to remove from the shared repository files that
are not used anymore, you should run a Mark and sweep procedure, to first mark all
archives that you want to preserve, end then sweep out of the registry all other files.
Note that there is normally little use to run such a process on the client computer,
except for special applications like frequent local backups.
Rembo-C provides a number of primitives for running a mark-and-sweep. These
functions are described in Section 5.4 in Rembo-C Scripting Reference Manual. The

22
Chapter 2. Working with Rembo
description also includes an example of a simple mark-and-sweep procedure.

2.5. Network protocols


Several network protocols are used for communications between the REMBO client
and the REMBO server. All these protocols are proprietary implementations built
for remote-boot applications.
The following table shows a summary of the protocols used by REMBO:
Table 2-2. Network protocols used by REMBO

NETfs UDP Unicast file protocol Used for reandom-access


net: files
MCAST UDP Multicast file Used when reading files
download protocol using cache: URLs
PCAST UDP Multicast file Used to download shared
download protocol files from the server
FAST UDP Unicast file upload Used when writing files
protocol using cache: URLs

The following sections discuss each protocol in more detail.

2.5.1. NETfs protocol


The NETfs protocol is used for all file operations performed on the server by the
REMBO client. Such operations include deleting a file, renaming a file, creating a
directory, searching for a file, ...
The NETfs protocol is also used for file transfers between the server and the client
(download) and between the client and the server (upload) when the file path starts
with net:.
NETfs is based on UDP and is a standard request-reply protocol. All packets from
and to the server are encrypted with a Blowfish 128bits encryption key negotiated
during REMBO startup. Fail-safe mechanisms are included to switch to a backup
server if the primary server fails.
NETfs is completely connection-less. It means that if for some reason the server
fails and is restarted, REMBO will automatically able to renegotiate a new
encryption key and continue the file operation.
Because NETfs is a request-reply protocol, file transfers might be less efficient with
NETfs than with the two other file protocols (MCAST and FAST).

2.5.2. MCAST protocol


The MCAST protocol is a multicast protocol used for file transfers from the server

23
Chapter 2. Working with Rembo
to REMBO clients. It is used by default when the file path starts with cache: or it
can be invoked with the Download function.

If there is no local partition, NETfs is used instead of MCAST for cache: files
download.

The MCAST protocol is based on UDP, and uses adaptive retransmit timeouts and
windowing techniques for maximum efficiency. By default MCAST file transfers
are not encrypted, but you can choose to encrypt MCAST transfers with the
MCASTEncrypt server parameter. Encrypted transfers will be slightly slower than
unencrypted transfers.
Contrary to other multicast protocols, MCAST does not require any synchronization
between client hosts. When a host wants to download a file using MCAST, it asks
the server for the file, and either join an existing multicast session, or start a new
one. If the client has joined a new session, it might not receive all the packets of the
file because it has joined the session after some part of the file has already been
sent. In this case, lost/missing packets will automatically be requested when the
client is selected as the primary workstation for the multicast session (the master).
Here is a simple rule you can use to determine how much time will be required to
download a file using MCAST on multiple clients:

• If there is only one client requesting the file, the file is transferred to the client in
X seconds;

• If there are several clients requesting the same file at the same time, the total
transfer time will be X+delta seconds, where delta is the time required for all
clients to request in turn their lost packets. If your network is not congested, you
expect delta to be near 0 because all clients are likely to receive the complete file
in one pass;
• If there are several clients requesting the same file at different times, you have to
consider the time at which the first client requested the file (time Ta), and the time
at which the last client joined the session (time Tb). It is clear that the first client
will terminate its transfer at time Ta+X. The last client will the last one to
terminate its transfer, at time Tb+X+delta. The total time will then be the
difference between the starttime Ta and the time at which the last client has
finished (Tb+X+delta).

Here is a real world example to illustrate the above formulas:

• Time to transfer the file (100MB): 100 seconds at 10Mb/s.

24
Chapter 2. Working with Rembo
• Two clients wants to download the file. First client will receive the file in 100
seconds. The second client joins the session 30 seconds after the file transfers has
been started by the first client. During 70 seconds, the second client will listen to
the packets requested by the first client, and store these packets on the hard disk.
When the first client has terminated (after 100 seconds), the second client has
30% of total packets missing because it has missed the 30 first seconds of the 100
seconds transfer. It will then request these packets from the server during 30
more seconds to complete its 100 seconds transfer. The total time for the transfer
will be 130 seconds, with 70 seconds of joined multicast session.

MCAST is a very efficient protocol. It can easily saturate a 10Mb/s network with
multicast traffic. If you want to limit the bandwidth used by MCAST to prevent
network congestion for other network users, you can set the variable
Settings.MCASTSpeed to a non-zero value to slow down the MCAST transfers.

If the variable Settings.UseMCAST is set to false, REMBO will use NETfs instead
of MCAST for downloading cache: files to the local cache partition.

MCAST is a protocol intended to transfer individual files. When downloading


multiple files (including shared files, into the shared files repository), it is
necessary to use the super-layer named PCAST, that can coordinate the
transfer of multiple files using MCAST.

2.5.3. PCAST protocol


As long as only one file is being transferred on the network at a time, MCAST in
native mode is the most efficient protocol to send this file to multiple clients
efficiently. However, if a group of clients is requesting multiple files in a short
period of time, you may observe several MCAST transfers on the network at the
same time because once a client has downloaded a file, it will request the next file,
while other clients may not have completed the download of the first file. The result
on the network is that multiple MCAST transfers will occur at the same time,
potentially causing network congestion, and timeouts. Congestion may occur on the
server side, because the server will have to generate multiple MCAST feeds on one
single network interface. Depending on how your network infrastructure is setup,
you may observe congestion on the client side. For example, if you do not use
switches on your network, or your switches are not configured for handling
multicast traffic (IGMP snooping), all concurrent multicast feeds will share the
same network bandwith, potentially causing network congestion, and time outs.
PCAST is a protocol designed as a super-layer of MCAST, and works as follow:

25
Chapter 2. Working with Rembo
• All participating clients have a list of files to download (which may be different
for each host), and a PCAST session name (which is the same for all hosts that
should participate to the same session).
• Every client in a PCAST session may specify the number of hosts to wait for, as
well as the desired timeout delay. The server will use the max of all values
specified by clients. The timeout value is used at the beginning of the transfer, if
the requested number of clients is not met, as well as during the transfer, if a
client is not requesting data blocks and has not signed out.
• The PCAST transfer is done by blocks of 16MB. The server waits for every
client to send a small file request list (1KB), and determines the content of the
next block based on these lists. When the server has built a full block, it first
sends a "table of contents" of the coming block, using the MCAST protocol.
Every client downloads this 16KB table of content.
• Every client parses the table of content, and determines the parts of the data
block that are of interest. The clients that need at least some part of the block start
a MCAST transfer of the block (download 16MB to memory). When every client
is done, data is saved to the corresponding files on disk and a new block can start
(file request, table of content then data transfer).

Files bigger than 16MB are automatically split into several blocks. Like MCAST,
the PCAST protocol supports to have additional clients joining a PCAST session
that has already started. The new clients will join on the next block, unless the block
is only the continuation of a file that has already started.
Shared files (to be downloaded to the shared repository) are handled as individual
files during a PCAST transfer, and indexed by content. That means that if you
download to different images of the same operating system simultaneously in the
same PCAST session (for instance for two different hardware), most of the image
content will only be transfered once in multicast, leading to a very efficient use of
the bandwidth.
PCAST is recommended for scheduled massive file transfers, involving multiple
files and large amount of data. Since PCAST requires some additional
synchronization before starting a transfer, it may take slightly longer than a
monolithic MCAST download for the same amount of data. However, the
scalability is definitely better for large transfers.
See the BatchTransfer function and the CopyCache function for more information
on how to launch a PCAST transfer.

2.5.4. FAST protocol


The FAST protocol is a unicast protocol used for file transfers from the REMBO

26
Chapter 2. Working with Rembo
client to the server (upload). It is used by default when the file path starts with
cache:, even if there is no local cache partition.

FAST has been designed to overcome limited NETfs performance when sending
large disk images to the server. It is based on UDP, and uses adaptive timeouts and
sliding windows to achieve optimal performance.
By default FAST file transfers are not encrypted, but you can choose to encrypt
FAST transfers with the FASTEncrypt server parameter. Encrypted transfers will be
slightly slower than unencrypted transfers.
FAST has been designed to use the most of the available bandwidth. In some
situations, it may be desirable to limit the efficiency of FAST to prevent network
saturation. To limit the bandwidth used by FAST, simply set the variable
Settings.FASTSpeed to a non-zero value. This will slow down FAST file transfers
and prevent network saturation.
Note that if each computer on the network is connected to a single port on a switch
(full switched network), FAST will have no influence on general network
performance since the switch will not propagate FAST traffic to other nodes (FAST
uses unicast datagrams). You may however notice a slight performance degradation
on other REMBO clients if the REMBO server CPU is saturated by the FAST
traffic. You can monitor this specific situation by using the Task Manager under
Windows NT, or top under Solaris/Linux.

2.6. Advanced cloning topics

2.6.1. Filtering files with Virtual Images


In some circumstances it may be required to backup only a subset of the reference
partition, or to filter some unwanted files, such as the memory paging file.
Virtual images can help you in this task. A virtual image is a copy of the directory
structure (only files and directories) of an existing filesystem. This virtual image can
then be modified by adding other filesystems (merge) or deleting files or directories.

If you want to remove only a few files from your reference partition before
creating a disk image, you may use RemoveFile instead, as it does not require
you to setup a virtual image. The difference between removing files with a
virtual image or removing files with RemoveFile is that virtual images do not
modify the reference partition, whereas RemoveFile actually removes the file
from the reference partition.
The process of creating a disk image from a virtual image is very simple:

• Create a virtual image of the reference partition

27
Chapter 2. Working with Rembo
• Optionally add another partition as a sub directory of the virtual image
• Remove unwanted files and directories, such as the paging file or temporary files
• Use Synchronize to build an disk image from this virtual image.
• Close the virtual images to release system resources

2.6.1.1. Creating the virtual image


Use CreateVirtualImage to create the virtual image from a reference partition. The
first parameter of this function is the name of the virtual image. This name is used
by other virtual image functions to identify the virtual image. The second parameter
is the path to copy directory structure from. It can be the root directory of a partition,
or a subdirectory if you want to backup only a subdirectory of the reference image.
Once the virtual image is created, you can access its content as any other filesystem,
by using the link: URL.
Example 2-3. Creating a virtual image

Here is an example on how to create a virtual image from the content of the first
partition, and then browse this virtual image with the file manager.
CreateVirtualImage("testimage","disk://0:1/");
FileMan("link://testimage/");

2.6.1.2. Adding files or directories to a virtual image


The LinkTree function allows you to link new files or directories to an existing
virtual image. For example, if you want to add the file net://group/testf in your
virtual image, type
LinkTree("link://testimage/dir3","net://group/testf");.

2.6.1.3. Removing files or directories from a virtual image


To remove files or directories from a virtual image, use the UnlinkTree function.
For example, to remove the file pagefile.sys from the root of your virtual image,
type UnLinkTree("link://testimage/pagefile.sys");.

2.6.1.4. Building a disk image from a virtual image


Once your virtual image is setup (you have added and removed files), you can
create a disk image from this virtual image with the Synchronize function. Use the
virtual image path as the first parameter of Synchronize.For example, to create a
disk image of the previously created virtual image, type
Synchronize("link://testimage/","cache://global/ntimage","");.

28
Chapter 2. Working with Rembo
2.6.1.5. Virtual images example
Here is a typical commands sequence used to create a disk image from a reference
partition, using virtual images to delete unwanted files:
CreateVirtualImage("winimage","disk://0:1/");
UnlinkTree("link://winimage/pagefile.sys");
UnlinkTree("link://winimage/hiberfil.sys");
Synchronize("link://winimage/","cache://global/winimage","");
FreeVirtualImage("winimage");

2.6.2. Incremental images


An incremental image is the difference between two filesystems, in terms of
files/directories added and files/directories removed. This difference can be stored
in a disk image, thus creating an incremental disk image.
Incremental images are useful for creating software installation packages
independently from the hardware installed. For example, you could create an image
of a newly installed Windows 98, and call this image win98base. Then, you could
create an incremental image of the same reference partition after having installed
MS Office on the computer. The incremental image will only contain MS Office
files and will be separate from the base disk image. If you repeat this procedure for
other softwares, you will have a software library ready for installation. Since these
incremental images are independent from the base image, you could install MS
Office on another base image (say, win98base2, a base image for a different
hardware) without recreating a new image.
Incremental images can also be used to support different kind of hardware with a
single base image by creating an incremental image for each kind of hardware. The
incremental image will be very small (it usually only contains new driver files).
Additionally, you can match hardware images with the hardware signature of the
target computer (see HWSignature) to automatically select the incremental image
adapted to your local hardware.

2.6.2.1. Basic incremental images


Basic incremental images are the simplest way to create incremental images. The
difference between the initial state and the new state, including configuration files
(e.g. registry files), is stored in one single file. On restoration, the configuration files
will be replaced by the version stored in the incremental image.
This method works well if you have are merging only one incremental image at a
time with the base image. If you want to merge more than one incremental image
(e.g. software package) with a base image, you must use advanced incremental

29
Chapter 2. Working with Rembo
images instead, because basic incremental images will not merge the content of
incremental images together inside configuration files (inside the registry).

2.6.2.2. Advanced incremental images


If you want to merge several incremental images together with a base image, you
must handle changes to configuration files separately. Depending on the operating
system you are cloning, you will have to perform additional steps to incremental
image creation:

• On Windows 95/98: registry files must be filtered out of the incremental image,
and must be handled separately with a registry patch file (.REG) for each
incremental image;
• On Windows NT: registry files must be filtered out of the incremental image, and
handled separately with individual incremental registry images for each
incremental image;
• On Linux: configuration files concerned by more than one incremental image
should be filtered out and handled separately with text differential patch files.

REMBO provides powerful tools for ease the creation of clean incremental images,
specifically for Windows NT/2000 for which the operation is the most complex.
The three basic functions for handling this operation are TextDiff,
MakeDiffFromText and ApplyDiff. See the individual manual pages of these
functions for the details on their use.
It should be understood that installing a software by snapshot is not intended as a
general alternative for software installers. It is only safe when used in the correct
environment, and when the snapshots have been created carefully. The difference
between a real installer and a software snapshot is that whereas the installer may be
aware of the present state of the computer and can act accordingly, the snapshot is
applied blindly and will therefore only do the correct work if the computer is in a
similar state as the reference image on which the snapshot was created.
A relatively safe place to use the snapshot technology is in conjunction with a
complete imaging process. In this context, the environment is precisely known and
does not depend on any previous user interaction or any past action performed on
the target system. The initial computer state is completely under control. It is
therefore possible to safely use software snapshots.
The purpose of creating incremental software images is obviously to reuse them in
several different circumstances, or to combine them in several ways. However, when
doing these combinations, you should keep in mind that if some of the incremental
images are not fully independant one of the other (which is the ideal case, but which

30
Chapter 2. Working with Rembo
is not always possible), you should apply them in the correct order so as to
reproduce the same environment originally present when each snapshot was created.
Special care must be taken if incremental images are used to handle
hardware-related components. The binding of hardware drivers into the operating
system may be tricky, and installing the same device in two different computer
models may lead to very different registry keys, which may in some case make it
impossible to use a common incremental image.
When using incremental images, you should also be aware of the fact that NTFS
security attributes associated with files are also part of the incremental. However,
the definition of users is usually not part of the incremental, but of the reference
image. Therefore, you should avoid creating incrementals with special user-related
permissions, as it could lead to permissions problems if the user does not exist in
the system profile being used for the final deployment.

2.6.2.3. How to create an incremental image


The base function for creating incremental images is the Synchronize function. The
first two parameters are the source and the destination of the comparison, and the
third parameter is used to tell REMBO where to store the difference (incremental
image).
Example 2-4. How to create an incremental image

To create an incremental image made of the difference between your reference


partition and your base disk image, type
Synchronize("disk://0:1/",
"cache://global/win98base",
">cache://global/msoffice");

This example will compare disk://0:1/ with the disk image


cache://global/win98base and store the result in cache://global/msoffice.

In most cases, you will need to filter the registry out of the comparison. To do this,
you must remove the registry from both the reference partition and the base disk
image, so that the registry is neither a new file, nor a deleted file. Virtual images
must be used to achieve this.
// 1. Remove the registry backups from the partition
RemoveFile("disk://0:1/windows/system.da0");
RemoveFile("disk://0:1/windows/user.da0");

// 2. Filter the registry with a virtual image


CreateVirtualImage("source","disk://0:1/");
UnlinkTree("link://source/windows/system.dat");
UnlinkTree("link://source/windows/user.dat");

// 3. Filter the registry in the disk image


OpenArchive("destarch","cache://global/win98base");

31
Chapter 2. Working with Rembo
CreateVirtualImage("dest","arch://destarch/");
UnlinkTree("link://dest/windows/system.dat");
UnlinkTree("link://dest/windows/user.dat");

// 4. Compare virtual images to create an incremental image


Synchronize("link://source/",
"link://dest/",
">cache://global/msoffice");

// 5. Free resources
FreeVirtualImage("dest");
FreeVirtualImage("source");
CloseArchive("destarch");

If you use TextDiff and MakeDiffFromText instead of Synchronize to create you


incremental image, the changes on the virtual image are done for you implicitely by
these functions. In addition, these functions allow you to specifically pick files that
should and should not be part of the incremental image. It is therefore highly
recommended to use these functions for creating incremental images, rather than
creating them directly. This is specially true for Windows NT/2000.
See Section 2.6.3 for instructions on how to restore incremental images.

2.6.3. Merging images using Virtual Images


If you created your incremental package using TextDiff and MakeDiffFromText
functions, you can use ApplyDiff to restore your incremental in one single
operation. The paragraph below shows you how to do the same operating manually.
If you created incremental images as described in Section 2.6.2, you will probably
have to restore multiple images on a single target partition: one base image, and one
image for each application selected by the user/by the computer profile. When
restoring multiple images to a single target partition, you have two choices:

1. Execute the RestoreDiskImage once for every image.


2. Use virtual images to merge disk images before restoration.

We strongly recommend you to use the second alternative, because it offers better
performance than the first one. Merging virtual file names is indeed easier and faster
than adding files to an existing filesystem.

32
Chapter 2. Working with Rembo
2.6.3.1. How to merge images together ?
Merging images before restoration is an easy process. You first need to create a
virtual image with your base image, and then add other images with the LinkTree
function. The following example shows you a typical commands sequence for
multiple images restoration.
Example 2-5. Restoring multiple image

In this example, we are about to restore the base image win98base and the two
incremental images msoffice and netscape on a single target partition, using
virtual images:
// 1. Create the virtual image
OpenArchive("base","cache://global/win98base");
CreateVirtualImage("virtual","arch://base/");

// 2. Add first incremental image


OpenArchive("incr1","cache://global/msoffice/");
LinkTree("link://virtual/","arch://incr1/");

// 3. Add second incremental image


OpenArchive("incr2","cache://global/netscape/");
LinkTree("link://virtual/","arch://incr2/");

// 4. Restore to the target partition


Synchronize("link://virtual/","disk://0:1/","b");

// 5. Free resources
FreeVirtualImage("virtual");
CloseArchive("incr2");
CloseArchive("incr1");
CloseArchive("base");

2.6.4. Converting partition types


A disk archive is usually restored on the same type of partition (FAT16, FAT32,
NTFS) as it was originally build on. As long as the restoration partition is big
enough to store the content of the archive, it does not have to be of the exact same
size as the original partition. However, when an operating system can live on several
types of partitions, it is not obvious to restore it on a kind of partition different from
the original one.
The two kind of partition conversion that you may want to do when restoring a disk
archive are:

• Windows 95/98: on FAT16 or FAT32

33
Chapter 2. Working with Rembo
• Windows NT/2K/XP: on FAT16 (BIGDOS) or NTFS

As REMBO use file-based disk archives, partition conversion is possible. The only
thing to care about is that a disk archive made for one type of partition may not have
all necessary information to rebuild a partition of another kind. Typically, the
operating will need a different boot sector depending on the type of partition used,
as the boot sector contains the bootstrap code necessary to locate the operating
system files located in the filesystem itself.
If you try to restore a disk archive on a partition of a type different from the one on
which it was created, you will receive a warning in the console log telling that the
boot sector was not compatible and was therefore skipped. That means, the partition
will have all the files properly restored but have no valid boot sector, and will
therefore not be bootable.
In order to make such a cross-restored archive bootable, you must proceed in the
following way:

1. Clean the target partition to ensure having a (non-bootable) bootsector with


correct size parameters
2. Restore a boot sector from any disk archive you have that matches the target
partition type
3. Restore all files from the partition you really want to have on the partition

Example 2-6. How restore an image on another type of partition

In practice, this can be done with a script as given below. We here assume the
restoration of a FAT32 image on a BIGDOS partition. In order to do so, you need to
have somewhere a BIGDOS archive (with anything on it, it does not matter) so as to
be able to take its boot sector.
// 1. Set the desired partition type
SetPrimaryPartitions(0,"BIGDOS:1000000");

// 2. Clean it
HDClean(0,1);

// 3. Restore the proper boot sector from any BIGDOS image.


// The restoration mode (b=) ensure no file is copied.
Synchronize("cache://global/hdimages/win9x/bigdos.img",
"disk://0:1", "b=");

// 4. Restore all files from the FAT32 image


// The empty mode does not alter the boot sector
Synchronize("cache://global/hdimages/win9x/fat32.img",
"disk://0:1", "");

34
Chapter 2. Working with Rembo

2.7. Starting REMBO without network connectivity


Although REMBO is primarily PXE-based, it can also work in many cases without
immediate network connectivity, when properly configured. The first situation is for
computers that have been started at least once with a PXE bootrom (or PXE boot
floppy), and prepared for use in off-line mode, using cached ressources. The second
situation when the REMBO server is replaced by a bootable CD-Rom or
floppy-disk. A third case is when REMBO is started off-line from a hard-disk or
CD-Rom, but then activates the PXE network adapter and contacts a REMBO
server (PXE activation).

2.7.1. Off-line mode


When connected to a server, REMBO can save accessed network files on-the-fly to
the hidden cache partition. This is done automatically for all files accessed through
cache:// URLs instead of net:// URLs. If all files are accessed this way, it is
possible for REMBO to start and work without network connection, in off-line
mode.

2.7.1.1. Configuring Off-line mode


In order to allow REMBO to start in off-line mode, you must ensure that the BIOS
setup allows booting on the hard-disk when PXE boot fails. Then, in the client
startup script, add a call to the SetOfflineMode function, to write a special boot
code on the hard-disk master boot record that will start REMBO. This call should
be after any command that changes the size of partitions. Also, do not clean the
MBR using HDClean or you would revert the work done by SetOfflineMode.
Start the client computer, ensure that the operating system images are downloaded
to the local cache partition by using them at least once (go through a full boot
sequence, up to starting the operating system). When this is done, try to remove the
network cable and restart the computer. After the PXE boot failure message, the
computer should start REMBO directly from the hard disk, as if it were connected
to the network. Even operating system restoration and self-healing should work as
usual.
If you want the computer to behave differently when running in off-line mode than
when running in on-line mode, you can write your off-line startup script and save it
as disk://0:-1/autoload. It will then be executed as a Rembo-C script instead of
displaying the usual rembo.shtml file.

35
Chapter 2. Working with Rembo

If you do not want to change your hard-disk master boot record, you can also
store REMBO off-line code in the boot sector of any primary partition (typically
the Linux partition, or an extended partition), and mark the choosen partition
as bootable.

2.7.1.2. How safe is off-line mode ?


Self-healing a computer in off-line mode is not exactly as safe as doing it with
network connectivity, as REMBO can only rely on local ressources, possibly
corrupted. However, it is at least much safer than booting directly on disk, as
REMBO is still able to restore the operating system to its configured stable state.
In practice, the cryptographic algorithms used to protect the cache partition ensure
that no accidental damage could result in corrupted system files. It does not prevent
an ill-intentionned user of making the computer unusable by completely
repartitioning and reformatting the hard-disk, but it can handle nicely several cases
of corruption.
As an alternative to working completely in off-line mode, PXE activation (see
below) can be used to retablish network connectivity after a boot on hard-disk.

2.7.1.3. REMBO as a boot manager


When configured in off-line mode, REMBO can work similarly to any boot
manager, offering a friendly graphical choice of operating systems to start. For
Linux users, it is our suggested replacement to LILO, as REMBO can start a Linux
kernel much the same way as LILO, but does not depend on the size and positino of
partitions as LILO does.

2.7.1.4. Off-line mode images


Although REMBO can work without network connectivity, the operating system
itself may have problems to start when trying to connect to the file server with
applicative files. One way to provide the user with a full backup solution in case of
network failure is to setup a network-less operating system image, with most useful
software included in the image. This way, users will be able to work as usual even if
the application server is down.

2.7.2. Booting REMBO from CD-Rom


It is sometime desirable to setup computers from scratch, without having a complete
PXE architecture. For this purpose, REMBO can create a bootable CD-Rom (aka
recovery CD) that can let a computer run REMBO out of the box, without network
connection,

36
Chapter 2. Working with Rembo
REMBO bootable CDs are as user-friendly and offer almost as much flexibility as a
fully networked REMBO client.

2.7.2.1. Generating a bootable CD-Rom


You create and configure a REMBO bootable CD exactly as you do for configuring
a networked client. Use the wizards to create disk images, and so on. When your
configuration is ready, setup the off-line mode, as described in Section 2.7.1.1, and
test it in several cases, to ensure that all necessary files are available and
downloaded to the cache partition. In this context, it is recommended to write an
autoload file (see above) that determines the off-line boot behaviour.

Then, use the CreateRemboCDRom function to generate a bootable ISO CD-Rom


image with all scripts and images that are currently loaded on the cache partition. If
the computer was able to run properly in off-line mode, the CD-Rom will contain
all necessary ressources to replace a server.
You will typically write the ISO CD-Rom image directly on the server, and then use
your CD-Rom writer program to write this ISO image directly on a CD-Rom (good
CD-Rom writer programs have a function to write an ISO image).
Once your CD is ready, you should be able to put it in any computer configured to
boot on CD-Rom, and have REMBO start automatically as expected.

2.7.3. Booting REMBO from a floppy


REMBO can be stored on a floppy disk image, using a procedure similar to what is
done for REMBO CD-Rom images. However, a floppy disk is limited to 1.44MB of
data, and therefore cannot be used for storing large images.
Just like for CD-Rom images (see Section 2.7.2.1), a REMBO floppy image
contains a copy of the local cache partition at the time of the floppy image creation.
You must ensure that the data on the local cache partition fits on a floppy or floppy
image creation will fail.
To create the floppy image, use the CreateRemboFloppy function to generate the
floppy image. It is recommended to store the floppy image in the path
cache://global/fdimages in order to be able to manage this floppy image with the
wizards.
You can test your floppy image by restoring it on a floppy disk using the wizards
(Floppy restoration), or using RestoreFloppyImage. Once the floppy disk is ready
for use, reboot your computer and boot on the floppy. You should be able to boot
REMBO and to access files stored on the floppy cache partition using
cache://global url prefix.

37
Chapter 2. Working with Rembo
2.7.4. Using PXE activation
As a complete PXE solution, REMBO now offers the possibility of using a PXE
network adapter even when the boot process has not been done through PXE. This
is called PXE activation.
PXE activation can add another level of security to public computers by ensuring
that even if the user has been able to redirect the boot to the hard-disk, REMBO will
still take over and reimage the disk from the server as usual.
PXE activation also opens the door to new applications, since it is possible to start a
networked REMBO-based configuration from a place without local REMBO boot
server, and to connect to any REMBO server available on the network.
The activation is done in two steps:

• First, the PXE ROM is loaded into low memory using the LoadUNDI function.
• Then, IP parameters are set using the SetIPInfo function.

IP parameters can be set either through DHCP, or using a fixed address. The address
of the REMBO server to use as primary server is specified in the call to SetIPInfo.
These calls are usually made in a function called from the autoload file in the
off-line configuration. For instance, a bootable REMBO floppy disk could
automatically connect to a predifined REMBO server.
If needed, one can detect whether a computer is running in off-line mode or in
on-line mode by checking if the host has an IP address:
if((int)NetInfo.IPAddress != 0) {
// running on-line
}

2.8. Using TCP tunnels to access remote resources


A TCP tunnel is a way to provide TCP connectivity in REMBO clients. A TCP
tunnel defines a hostname and a port which is made accessible to REMBO clients
through specific Rembo-C clients.
TCP tunnels can be used to provide a wide range of interesting applications on the
client-side. Here are some examples:

• Access to a SMTP server to send mail to an administrator if something wrong


has been detected by REMBO;

38
Chapter 2. Working with Rembo
• Access to a database server (through an TCP-to-ODBC gateway) to get
information or instructions on what kind of operation to perform, or to store
information about the computer (hardware inventory);
• Access to a HTTP server (web server) to retrieve information directly from the
world-wide-web;
• Access to proprietary management suites, or to interface with specific
authentication methods.

The following sections describe two TCP applications implemented as examples in


REMBO distribution. Note that ODBC connectivity is only available in the
Enterprise Edition.

2.8.1. Sending emails with REMBO


You can send emails directly in REMBO, using the SendMail Rembo-C function.
This feature can be used to send alerts to the system administrator when a
corruption is detected by REMBO, or when a user requests support because his
computer does not boot anymore.
In order to use SendMail to send messages, you must first add a TCP tunnel in your
server configuration. The identifier for this new tunnel must be sendmail, and the
RemotePort parameter must be 25. The last parameter, RemoteHost, must be set to
the IP address or hostname of your SMTP server (outgoing mail server).

See Section 2.4 in REMBO Server Administration Manual for more


information about TCP tunnels, and instructions on how to create a new TCP
tunnel.
Once the tunnel is setup on the server, reload the configuration or restart the server
to make sure that the changes are committed. On the client side, run
join(Exec("cache://global/plugins/sendmail.rbx")); to have access to the
SendMail.

You can then use SendMail as described in the manual page for SendMail to send
messages.

2.8.2. Database access in REMBO


Database access under REMBO works as follow: a TCP tunnel routes database
queries from the REMBO client to a database gateway installed on the computer
running REMBO server. The gateway forwards the query to the database server.
The results are sent back using the same path (gateway, TCP tunnel).

39
Chapter 2. Working with Rembo
The database gateway answers requests coming from the local interface only (i.e.
127.0.0.1). This prevents other computers than the REMBO server to access the
database through the gateway. A TCP tunnel must be setup on the REMBO server
to allow REMBO clients to access the gateway directly. The RemoteHost parameter
has to be set to "127.0.0.1", while the RemotePort parameter has to be set to 2020.
Two different versions of the database gateway are provided with Windows NT and
Unix REMBO servers. On Windows NT, the database gateway is an executable that
runs as a Windows service and uses ODBC, the default database access service of
Windows. On Unix systems, the database gateway is a Java application that uses
JDBC, Java’s solution to interact with the databases of different vendors.

2.8.2.1. Gateway on Windows NT


On Windows NT systems, ODBC support is available as part of the operating
system. All you have to do is to make sure that an ODBC driver for your database
server is present on the system. Most database servers provide ODBC drivers,
including shareware servers like MySQL.
You should also configure a proper ODBC System DSN that points to your database.
Creating a System DSN is compulsory to use the simple function SQLOpen. It is also
possible to connect without DSN using the more complex function SQLOpenEx
"bracket syntax".
The database gateway is automatically installed as a service (RemboODBC) by the
InstallShield. If you’ve chosen to store REMBO parameters in the registry, the
required TCP tunnel is created automatically and the gateway is automatically
started when the REMBO service is running.
If your server is configured using a rembo.conf file, you have to configure the TCP
tunnel yourself, as described above. The RemboODBC service must also be started
manually.
The gateway executable dbgw.exe has several options:

• -i installs the service


• -u uninstalls the service
• -v level sets the verbosity level (same as REMBO server)
• -t seconds closes connections after an inactivity period (default is 120)
• -d same as -v 1

40
Chapter 2. Working with Rembo
2.8.2.2. Gateway on Unix
On Unix systems, the database gateway is provided as a Java application
(dbgw.jar).

Before you can use the gateway, you must have the Java and the JDBC driver
for your specific database on your system.

The syntax to start the service is


java -cp dbgw.jar -Djdbc.drivers=<drivers> com.rembo.dbgw.Dbgw [-d] [-t seconds]

where the option -d can be used for debugging and -t seconds closes connections
after an inactivity period (default is 120).
For instance, if you have MySQL, use:

java -cp dbgw.jar -Djdbc.drivers=org.gjt.mm.mysql.Driver com.rembo.dbgw.Dbgw

If your REMBO server runs on a Solaris or Linux computer, you may also choose
the ODBC way, but that’s not required. Install the unixODBC package available at
http://www.unixodbc.org. This package adds ODBC functionalities to unix
operating systems, and to most known database servers (MySQL and PostgreSQL).
Note that installing ODBC will not free you from using Java and JDBC.

2.8.2.3. Accessing from the client


Accessing a database from your REMBO client requires the following steps:

• Have a database server ready.


• On the computer running REMBO server, start the database gateway. Make sure
that it is running using the command telnet localhost 2020.
• Make sure that the ODBC TCP tunnel is configured on the REMBO server. Use
the following parameters: RemoteHost must be "127.0.0.1", and RemotePort
must be 2020.
• To use database functions in Rembo-C scripts, you must first load the script
/plugins/sql.rbx. You can use the following command to load sql.rbx:
join(Exec("cache://global/plugins/sql.rbx"));

41
Chapter 2. Working with Rembo
Once all the above operations are performed, you can access your database server
with the following functions:

• SQLOpen and SQLOpenEx to open a database session;


• SQLQuery to execute a SQL query;
• SQLClose to close a database session;
• SQLQuickQuery to open a session, execute a query and close the session in one
operation.

See also Section 5.9 in Rembo-C Scripting Reference Manual for more information.

42
Chapter 3. OS-Specific Instructions

This chapter describes in details the procedure to clone each type of OS. The
procedure differs from one OS to the other, not because of the cloning mechanism
itself, but because of the post-cloning automatic reconfiguration that you want to set
up.

3.1. Cloning MS-DOS

3.1.1. Cloning a MS-DOS system


Prepare a reference workstation with a typical MS-DOS installation on the first
partition of the hard disk. Make sure that you do not leave temporary files on the
reference partition. We recommend that you create a file called rembo.bat in the
root directory of your reference partition, and add the line call c:\rembo.bat
somewhere in your autoexec.bat. This will make it possible to customize your
MS-DOS image at runtime by adding commands in the rembo.bat file. On the
reference partition, just leave your rembo.bat empty.
Start the client computer with REMBO. Create your image with BuildDiskImage as
described in Section 2.3.1. Let the image be called
cache://global/images/dosimage.

To restore the image on a target computer, use RestoreDiskImage as described in


Section 2.3.2. Do not forget to create a valid FAT partition on the target computer
prior to running RestoreDiskImage.

3.1.2. Customizing a MS-DOS system


You may need to modify system files at run-time, when the disk image has been
restored on the target computer. Depending on your requirements, you will either
need to modify autoexec.bat to add new commands or modify a system file to
reflect the information REMBO has collected about your target computer (for
example, add environment variables containing a username or an IP address).
If you have created a rembo.bat file during the creation of the disk image, then you
will be able to add commands or environment variables by modifying this file, since
it is called from the autoexec.bat script at startup. To modify your rembo.bat from
REMBO, create a template file on the server and use the PatchFile command to
copy the template to disk://0:1/rembo.bat, with automatic expression
substitution on the fly. See the manual page of PatchFile for more information
about the syntax used in substitution expressions.

43
Chapter 3. OS-Specific Instructions
Example 3-1. Patching rembo.bat

This example shows the content of the template file and the content of the
rembo.bat file after copying the template over the target file with PatchFile.

Content of the template file:


ECHO "Installing environment variables"
SET IPADDRESS={$NetInfo.IPAddress$}
SET HOSTID={$NetInfo.MACAddress$}
SET USERNAME={$AuthInfo.UserName$}
SET FULLNAME={$AuthInfo.FullName$}
SET DOMAIN=COMPANY

Content of the patched file:


ECHO "Installing environment variables"
SET IPADDRESS=192.168.1.10
SET HOSTID=00 90 27 12 34 56
SET USERNAME=rembotest
SET FULLNAME=Rembo tester
SET DOMAIN=COMPANY

The command used to generate the rembo.bat patched file is


PatchFile(NetFile("rembo.bat.tmpl"),"disk://0:1/rembo.bat");

.
We recommend that you use the NetFile function to further customize your hosts.
The NetFile function first tests if the file exists under the net://host/ level, then
tries the net://group/ level and finally uses the net://global/ if the file does not
exists at neither the host or the group level. The use of NetFile makes it possible to
add custom behaviour for a group of hosts or a single host by simply adding the
rembo.bat.ref in the proper location on the server (see the net: URL manual page
for more information).

PatchFile can also be used to modify a system file, for example a configuration file
used by your MS-DOS TCP/IP stack. You can use REMBO to insert the proper
network information (hostname, IP address, ...) in the configuration file. See Section
2.2 for a list of available variables.

3.1.3. Installing Lan Manager clients for UNDI


LanMan clients are Microsoft Network clients for MS-DOS. They can be used to
access a Windows NT server from MS-DOS.
LanMan uses a NDIS network driver to access the network hardware. This driver is
usually provided by your network card vendor. Recently, Intel has developed an

44
Chapter 3. OS-Specific Instructions
universal NDIS driver that makes use of the PXE bootrom to provide network
access to LanMan. If you use this driver, your LanMan installation will work on all
PXE network cards if booted through REMBO.
Read the page http://www.rembo.com/rembo/resources.html to get links to
different files needed for LanMan. You will also find examples of patch files for
LanMan configuration files.
To install LanMan clients, follow these simple steps:

• Download the three LanMan disks and the Intel NDIS driver;
• Create an empty but bootable MS-DOS partition and install the three LanMan
disks on this partition;
• Copy the Intel NDIS driver and change the LanMan configuration files to use
this driver;
• Make an image of this partition with REMBO
• Restore the image and boot with DeviceBoot("disk://0:1",false); instead of
HDBoot(0,1); to keep the PXE bootrom loaded into the memory;

• Check that everything is working properly;

3.2. Cloning Windows 95/98/ME


This section describes how to create a Windows 95/98/ME base image, how to
create incremental images and how to customize your target computer after
restoration (e.g. change the hostname).
Most of the operations described in this section can be performed with the wizards.
This section shows how to perform these operations with Rembo-C scripts.

3.2.1. Creating a Windows 9x base image


This first section describes how to create a complete image of your Windows
95/98/ME hard-disk. This image is important as it will be the base for incremental
images, and it is also your emergency backup if your hard disk is corrupted.
Set up a regular Windows 95/98/ME client, either starting from scratch (as
explained in the configuration of a MS-DOS client), or starting from the MS-DOS
client and installing Windows over the network. You can also use a
manufacturer-preconfigured Windows machine. To simplify the instructions, we
will assume that you installed Windows on the first partition of the hard disk.
Create a file called rembo.bat in the root directory, and add the line call
c:\rembo.bat somewhere in your autoexec.bat. This will make it possible to

45
Chapter 3. OS-Specific Instructions
customize the boot process at runtime by adding commands in the rembo.bat file.
On the reference partition, just leave a rembo.bat file empty.
Now start REMBO, and evaluate FileMan("disk://0:1"); to browse the content
of your Windows partition. Then, close the file manager and use the following
simple script to create the base image:
// Step 1. Create a virtual image of the disk
CreateVirtualImage("win9x","disk://0:1");

// Step 2. Remove the swap file from the virtual image


RemoveFile("link://win9x/windows/win386.swp");

// Step 3. Remove any previous version of the archive


if(FileExists("cache://global/hdimages/win9x/baseimage.img"))
RemoveFile("cache://global/hdimages/win9x/baseimage.img");

// Step 4. Create an archive of the virtual image


Synchronize("link://win9x",
"cache://global/hdimages/win9x/baseimage.img","");

// Step 5. Free resources


FreeVirtualImage("win9x");

The above script stores the content of your hard disk in the file
cache://global/hdimages/win9x/baseimage.img on the server. You can remove
other files or directory (e.g. temporary files) to prune unwanted files from the
image. Files or directories removed during Step two are not actually removed from
the hard disk because we use a virtual image (a virtual image is a copy of the disk
structure used to edit directories without modifying the underlying device).
Now you have a backup of your reference workstation on the server. The next step
is to test that this backup image is valid.

3.2.2. Testing the base disk image


You must now verify that your base disk image works by restoring the disk image.
It is recommended to restore the image on a different computer as the one used for
the reference image to prevent corrupting the reference workstation if something
went wrong.
Start REMBO, setup the partitions with the wizards (do not forget to leave some
room at the end of the hard disk for the local cache partition). Then restore your
Windows 9x image with the following command:
RestoreDiskImage(0,1,"cache://global/hdimages/win9x/baseimage.img");

46
Chapter 3. OS-Specific Instructions
Once download and restoration is completed, run FileMan("disk://0:1"); to
browse the files created on your hard disk. run HDBoot(0,1); to boot on your
Windows 95/98/ME partition.
At this stage, you have a complete backup of your reference computer in case of
problem during the next steps of this tutorial. You can at any time revert to this
initial state by restoring the base image again.

3.2.3. Create a restoration script


This section explains how to automate the restoration process in a script.
You can use the following script to restore your base image to a workstation. This
script performs the following actions:

• Setup partitions to a state compatible with the image;


• Restore the base image;
• Compute an unique computer name and create a registery patch to be applied
before Windows starts;
• Boot.
// Step 1. 1GB FAT16 (so-called BIGDOS) partition
SetPrimaryPartitions(0,"BIGDOS:1000000");

// Step 2.
RestoreDiskImage(0,1,"cache://global/hdimages/win9x/baseimage.img");

// Step 3a. Host name is based on the last bytes of the IP address
var ipa = StrParse(NetInfo.IPAddress,".");
str Hostname = "PC-"+ipa[2]+"-"+ipa[3];

// Step 3b. Build a registry patch to setup the host name


CreateTextFile("disk://0:1/rembo.reg",
"REGEDIT4\n\n"
"[HKEY_LOCAL_MACHINE\\System\\CurrentControlSet"
"\\Services\\VxD\\VNETSUP]\n"
"\"ComputerName\"=\""+Hostname+"\"\n\n"
"[HKEY_LOCAL_MACHINE\\System\\CurrentControlSet"
"\\Services\\VxD\\MSTCP]\n"
"\"HostName\"=\""+Hostname+"\"\n\n"
"[HKEY_LOCAL_MACHINE\\System\\CurrentControlSet"
"\\control\\ComputerName\\ComputerName]\n"
"\"ComputerName\"=\""+Hostname+"\"\n");

// Step 3c. Add a call to regedit in our startup batch


CreateTextFile("disk://0:1/rembo.bat",
"c:\\windows\\regedit"
" /L:c:\\windows\\system.dat"
" /R:c:\\windows\\user.dat"
" c:\\rembo.reg");

47
Chapter 3. OS-Specific Instructions

// Step 4. Boot on the disk


HDBoot(0,1);

To use the above script, save it in a separate file, copy the script file on the server
and type Exec("net://global/scriptname"); (replace scriptname with the name
of your script).
To execute this script automatically, create a HTML page containing a welcome
message and a <SCRIPT> section, like it is done in the rembo.shtml file. Add the
Exec function call in the script section of your HTML page, or simply copy-paste
the script content. Then, change the StartPage server parameter for your test hosts
to the REMBO URL of your newly created HTML page.
You can customize the script for your needs. If you want to create two partitions,
one for the system and one for data, simply add a BIGDOS:xxx entry in the partition
string, and do not forget to quick-format this partition at least once with HDClean:
SetPrimaryPartitions(0,"BIGDOS:500000 BIGDOS:500000");
HDClean(0,2);
...

You can use a persistent variable to determine if it is the very first time this script is
run, and therefore run HDClean only once.
If you want to use FAT32 partitions instead of FAT16, use FAT32:xxx entries in the
partition string. However, be aware that FAT16 and FAT32 do not use the same boot
sector. Therefore, if you restore a FAT16 archive on a FAT32 partition (or
vice-versa), the boot sectore will not be restored and the disk will not be bootable.
Read Section 2.6.4 for instructions on how to restore an archive on a type of
partition different from the one on which the archive was created.

3.2.4. Synchronizing instead of RestoreDiskImage


You can greatly improve the speed of the restoration process by avoiding to remove
all files before restoring an archive. If the partition contains files, REMBO will
attempt to synchronize the content of the partition with the disk image, rather than
blindly restoring everything. If most of the files on the partition have not changed
between two restorations, the synchronize mode will be much faster than a blind
restoration. To use synchronization, replace Step two of the restoration script by the
following code:
// Step 2. Smart synchronization
DeviceCheck("disk://0:1",true,true);
Synchronize("cache://global/hdimages/win9x/baseimage.img",

48
Chapter 3. OS-Specific Instructions
"disk://0:1","b");

See the Synchronize manual page for more information about different
synchronization modes. The call to DeviceCheck ensures that the target partition is
free of errors before starting the synchronization process. Note that DeviceCheck
may not be supported on all filesystem types.
If the partition is corrupted because Windows 9x was powered off without using the
shutdown sequence, the synchronize mode of REMBO might fail because of
corrupted files. You can implement fail-safe restoration by formatting the hard disk
if synchronize fails to restore the image. The following example uses an exception
handler to trap synchronize errors and clean the partition:
var SyncErrorHandler(var exc)
{
Log("Restoration failed. Rebooting<br>");
// Clean the partition
HDClean(0,1);
// Wait 2 secs
delay(200);
// Reboot the computer to go in a safe state
Reboot();
}
// Synchronize:
with (SyncErrorHandler) try {
Synchronize("cache://global/hdimages/win9x/baseimage.img",
"disk://0:1","b");
}
Log("Restoration successful<br>");

You may want to replace HDClean() with DeviceCleanEx() as explained in


Section 2.3.3 if you want to preserve the filesystem structure when formatting
the partiton.

3.2.5. Customizing
The target computer customization is a very important phase of the cloning process.
This phase sets custom parameters into the Windows 9x configuration files to
prevent conflicts due to the fact that all cloned computer have the same name, or to
make host-specific or hardware-specific changes.
As Windows 95/98 are based on MS-DOS, some of the system and software
parameters are stored in text files (win.ini, system.ini. However, most of them
tend now to be stored in the registry files. REMBO is not yet able to directly change

49
Chapter 3. OS-Specific Instructions
the content of Windows 95/98 registry (the registry functions available in REMBO
Professional and REMBO Enterprise only work for Windows NT registry).
However, Windows 95/98 include a program named regedit to patch the registry
before starting windows, that can be started from the autoexec.bat startup file for
instance. Consequently, all you have to do in order to customize the settings of a
Windows 95/98 station is to perform some text file editing with REMBO scripts and
setup an automatic registry patch on startup (as it has been done in Section 3.2.3). in
If you want to modify a specific registry key, use the following generic procedure
(which is actually more elegant than directly writing a registry patch as shown in
the previous section):

1. Under Windows 95/98, run REGEDIT and locate the parameters you want to
change. Computer settings are stored in HKLM/System/CurrentControl. If
needed, use the Search... function to locate the setting you are looking for.
2. Select the branch you want to parametrize, and use the function Export in the
menu to save this branch in a text file (with the extension .REG).
3. Edit the exported file (with Notepad or any other text editor) and replace the
values you want to change by patch patterns (for instance {$Hostname$}).
4. Upload the modified registry patch file to the server, using netclnt or the server
console.
5. Add a line to your restoration script to generate a host-specific registry patch
file on the disk, based on the generic patch file you have uploaded on the server.

For instance, you could use the following generic registry patch file to change the
host name of the computer:
REGEDIT4

[HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\VNETSUP]
"ComputerName"="{$Hostname$}"

[HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\MSTCP]
"HostName"="{$Hostname$}"

[HKEY_LOCAL_MACHINE\System\CurrentControlSet\control\ComputerName\ComputerName]
"ComputerName"="{$Hostname$}"

Assuming you have saved this file on the REMBO server under
hdimages/win9x/baseimage.reg, you can replace the Step 3b in Section 3.2.3 by
the following command:
// Copy and patch the host-specific registry settings

50
Chapter 3. OS-Specific Instructions
PatchFile("cache://global/hdimages/win9x/baseimage.reg",
"disk://0:1/rembo.reg");

3.2.6. Basic incremental images


Basic incremental images are images containing the difference between two states
of a hard-disk, but without handling the registry differences. Registries are handled
as modified files, and will be included in the incremental image, and restored
blindly on restoration. This does not cause any problem if you work with only one
incremental image at a time, because the registries will be restored in the state of the
incremental image. But if you want to use several incremental images, and merge
these images together to create one single final state, you must handle registry files
explicitely, because you have to merge changes to the registry files as well.
The first thing to do before creating an incremental image is to install an additional
driver or software on the workstation, in order to have something to store in the
incremental image.
To create an incremental image, simply run the Synchronize in incremental mode
on your hard-disk. The following example compares the content of the partition
with the base image and creates an incremental image on the server (third
parameter):
Synchronize("disk://0:1",
"cache://global/hdimages/win9x/baseimage.img",
">cache://global/hdimages/win9x/baseimage.diff");

The name of your incremental image does not need to be similar to the name of the
base image. We choosed similar names for the sake of clarity.
To restore your incremental image on top of your base image, you must merge the
incremental image with the base image. The easiest way to perform this action is to
use a virtual image. Once the virtual image is created by merging the incremental
and the base image, you can restore this virtual image on the Windows partition in
full restoration mode (i.e. HDClean followed by Synchronize) or in synchronization
mode. Here is a sample script, similar to the script used for the base image
restoration, but with the addition of the incremental image:
// 1. Open the two disk archives (base and diff)
OpenArchive("base","cache://global/hdimages/win9x/baseimage.img");
OpenArchive("diff","cache://global/hdimages/win9x/baseimage.diff");

// 2. Create a virtual image on the base archive


CreateVirtualImage("win9x","arch://base");

51
Chapter 3. OS-Specific Instructions
// 3. Merge the incremental image into the virtual image
FileLink("link://win9x","arch://diff");

// 4. Synchronize the content of the disk with the virtual image


Synchronize("link://win9x","disk://0:1","b");

// 6. Free used resources


FreeVirtualImage("win9x");
CloseArchive("diff");
CloseArchive("base");

3.2.7. Advanced incremental images


You will need advanced incremental images if you want to merge more than one
incremental image with the base image. Advanced incremental images are more
complex to manage than basic incremental images, but they allow more flexibility.
With advanced incremental images, you can create an incremental image per
software, and merge softwares together with the base image at run time depending
on what the user choose, and restore this to the disk quickly.
Here is the procedure to follow to create an advanced incremental image:

1. Restore the base image on a workstation (with no additional incremental


image). This is is called the original state.
2. From this safe state, install the required software. The computer will be in the
final state. The goal of an incremental image is to contain all the differences
between the original state and the final state, so that it is possible to regenerate
the final state from the original state.
3. Create an incremental image with all modified files, excepted system
configuration files (mainly the registry, but possibly also win.ini, system.ini,
autoexec.bat and config.sys...).

4. Create the generic configuration patches and the script necessary to replay the
changes on the system configuration files.

Here are the details for the creation of the incremental image for disk files and the
registry:
When your software is installed (point 2 of the procedure), start REMBO and run
the following script. This script uses a virtual image to prune the registry files from
the comparison between the disk content and the base image. The resulting
incremental image will not contain the registry files.

52
Chapter 3. OS-Specific Instructions
// 1. Create a virtual image of the disk
CreateVirtualImage("win9x","disk://0:1");

// 2. Prune registry files


RemoveFile("link://win9x/windows/user.dat");
RemoveFile("link://win9x/windows/system.dat");

// 3. Create the incremental image


Synchronize("link://win9x",
"cache://global/hdimages/win9x/baseimage.img",
">cache://global/hdimages/win9x/mysoft.diff");

// 4. Free resources
FreeVirtualImage("win9x");

The above script creates the incremental image for files only. In order to apply the
corrsponding changes to the registry, you must manually create a registry patch by
comparing the base image registry and the modified registry. This can be done using
the following procedure:

1. On a computer configured in the original state (base image only), run


REGEDIT and export the whole HKEY_LOCAL_MACHINE branch to a text file
named baseimage.reg.
2. On the computer where you installed the software, run REGEDIT and export
the whole HKEY_LOCAL_MACHINE branch to a text file named mysoft.reg.
3. Copy both files to a temporary directory on a computer, open a MS-DOS
window, and in this directory, run the command below to automatically lookup
all differences between the two versions of the registry:
fc baseimage.reg mysoft.reg > mysoft.diffreg

4. Using a text editor, open the three files simultaneously, and edit the difference
so as to build a valid registry patch, looking for possibly missing branch
selectors in the original files. Ensure to add the REGEDIT4 keyword at the
beginning of the file, followed by an empty line, and to have all key/value pairs
prefixed by the appropriate branch selector.
5. Upload the resulting registry patch on the server as
hdimages/win9x/mysoft.reg.

53
Chapter 3. OS-Specific Instructions
3.2.7.1. Restoring an advanced incremental image
Restoring an advanced incremental image is done in three steps:

1. Create a virtual image to merge the base image with the incremental image for
files;
2. Restore the virtual image;
3. Install the registry patch.

Step one and three can be changed to merge more than one incremental image.
Once you have understood how it works for one image, you copy the Rembo-C
statements for other incremental images to create a complex script.
Here is a complete example of restoration, with inline comments to clarify
individual steps:
// Step 1a. Open the disk archives
OpenArchive("base","cache://global/hdimages/win9x/baseimage.img");
OpenArchive("diff1","cache://global/hdimages/win9x/mysoft.diff");

// Step 1b. Create the virtual image on the base image


CreateVirtualImage("win9x","arch://base");

// Step 1c. Merge the incremental archive in the virtual image


LinkTree("link://win9x","arch://diff1");

// Step 2a. Restore the files


// This will restore registry files from the base image,
// in ’initial state’
Synchronize("link://win9x","disk://0:1","b");

// Step 2b. Free resources


CloseArchive("diff1");
FreeVirtualImage("win9x");
CloseArchive("base");

// Step 3a. Setup all registry patch


str regcmd = "c:\\windows\\regedit"
" /L:c:\\windows\\system.dat"
" /R:c:\\windows\\user.dat";
CreateTextFile("disk://0:1/rembo.bat",
regcmd + " c:\\rembo.reg\n" +
regcmd + " c:\\mysoft.reg\n");

// Step 3b. Install the hostname registry patch


PatchFile("cache://global/hdimages/win9x/baseimage.reg",
"disk://0:1/rembo.reg");

// Step 3c. Install the software registry patch


PatchFile("cache://global/hdimages/win9x/baseimage.reg",

54
Chapter 3. OS-Specific Instructions
"disk://0:1/mysoft.reg");

... customize hostname and boot

This procedure relies on the use of the REGEDIT program in real mode.
Unfortunately, this program sometimes has problems when dealing with large
registry patches, probably due to conventional memory restrictions. If you are
facing such kind of problems (for instance when applying this method to install
Microsoft Office), you should consider the following work-arounds:

• Splitting the registry patch in two or more smaller patches


• Using a third-party program to clean-up the registries (before exporting
them as .REG files).
• Setting up an extended memory manager to maximize the conventional
memory available to REGEDIT.
• Importing the registry changes for the software in the base image, as they
will usually not disturb.

If you need to merge more than one incremental image with the base image, you
must do the following changes to the above script:

• Extend step 1a and repeat step 1c for other incremental images (to merge all
incremental images in one virtual image). Do not forget to close the opened
archives after the Synchronize statement;
• Extend step 3a and repeat step 3c for other registry patches (to apply
sequentially all registry patches).

3.2.7.2. Going further


As you start using advanced incremental restoration, you should consider reading
the description of all commands related to disk restoration, virtual images, NT
registry and archives to have a better overview of advanced cloning methods
described in this section.
There are many ways to combine these commands to automatically install or refresh
a computer depending on the hardware, on the user profile, on the computer group
and so on. However, such procedures go beyond the scope of this document. With

55
Chapter 3. OS-Specific Instructions
some programming experience and some imagination, you should be able to do
almost anything with REMBO. If you face a problem, you can try to share it with
other REMBO users on the support forum.

3.3. Cloning Windows NT


This section describes how to create a Windows NT base image, how to create
incremental images and how to customize your target computer after restoration
(e.g. change the hostname).
These instructions are based on Windows NT 4.0, but works with Windows 2000
and Windows XP, too.
Most of the operations described in this section can be performed with the wizards.
This section shows how to perform these operations with Rembo-C scripts.

3.3.1. Creating a Windows NT base image


This first section describes how to create a complete image of your Windows NT
hard-disk. This image is important as it will be the base for incremental images, and
it is also your emergency backup if your hard disk is corrupted.
Install Windows NT on a clean workstation, with no other operating system
installed. During setup, select DHCP when asked for the network interface
configuration parameters. Give a name to the workstation, and join your NT domain
or workgroup.
Start REMBO, and try FileMan("disk://0:1"); to browse the content of your
Windows NT partition. Then, close the file manager and use the following simple
script to create the base image:
// Step 1. Create a virtual image of the disk
CreateVirtualImage("nt","disk://0:1");

// Step 2. Remove the swap file from the virtual image


RemoveFile("link://nt/pagefile.sys");
if (FileExists("link://nt/hiberfil.sys"))
RemoveFile("link://nt/hiberfil.sys");

// Step 3. Remove any previous version of the archive


if(FileExists("cache://global/hdimages/winnt/baseimage.img"))
RemoveFile("cache://global/hdimages/winnt/baseimage.img");

// Step 4. Create an archive of the virtual image


Synchronize("link://nt",
"cache://global/hdimages/winnt/baseimage.img","");

// Step 5. Free resources


FreeVirtualImage("nt");

56
Chapter 3. OS-Specific Instructions

The above script stores the content of your hard disk in the file
cache://global/hdimages/winnt/baseimage.img on the server. You can repeat
Step two for other files or directory (e.g. temporary files) to prune unwanted files
from the image. Files or directories removed in Step two are not actually removed
from your hard disk because we use a virtual image (a virtual image is a copy of the
disk structure used to edit directories without modifying the underlying device).
Now you have a backup of your reference workstation on the server. The next step
is to check that this backup image is valid.

3.3.2. Testing the base disk image


You must now verify that your base disk image works by restoring the disk image.
It is recommended to restore the image on a different computer as the one used for
the reference image to prevent corrupting the reference workstation if something
went wrong.
Start REMBO, setup the partitions with the wizards (do not forget to leave some
room at the end of the hard disk for the local cache partition). Then restore your
Windows NT image with the following command:
RestoreDiskImage(0,1,"cache://global/hdimages/winnt/baseimage.img");

Once download and restoration is completed, run FileMan("disk://0:1"); to


browse the files created on your hard disk.
Type NTSetNetbiosName("NEWNAME"); to change the name of your newly create
NT workstation to "NEWNAME" and run HDBoot(0,1); to boot on your Windows NT
partition.
At this stage, you have a complete backup of your reference computer in case of
problem during the next steps of this tutorial. You can at any time revert to this
initial state by restoring the base image.

3.3.3. Create a restoration script


This section explains how to automate the restoration process in a script.
You can use the following script to restore your base image to a workstation. This
script performs the following actions:

• Setup partitions to a known state;


• Restore the base image;

57
Chapter 3. OS-Specific Instructions
• Compute an unique computer name and change the NT workstation name in the
Windows NT registry;
• Boot.
// Step 1. 1.5GB NTFS partition
SetPrimaryPartitions(0,"NTFS:1500000");

// Step 2.
RestoreDiskImage(0,1,"cache://global/hdimages/winnt/baseimage.img");

// Step 3. Name is based on the last bytes of the hardware address


var hwa = StrParse(NetInfo.MACAddress," ");
str name = "NTRBO-"+hwa[4]+hwa[5];
NTSetNetbiosName(name);

// Step 4.
HDBoot(0,1);

To use the above script, save it in a separate file, copy the script file on the server
and type Run("net://global/scriptname"); (replace scriptname with the name
of your script).
To execute this script automatically, create a HTML page containing a welcome
message and a <SCRIPT> section, like it is done in the rembo.shtml file. Add the
Run function call in the script section of your HTML page, or simply copy-paste the
script content. Then, change the StartPage server parameter for your test hosts to
the REMBO URL of your newly created HTML page.
You can customize the script for your needs. If you want to create two NTFS
partitions, one for the system and one for data, simply add a NTFS:xxx entry in the
partition string, and do not forget to quick-format this partition at least once with
HDClean:
SetPrimaryPartitions(0,"NTFS:1500000 NTFS:3500000");
HDClean(0,2);
...

You can use a persistent variable to determine if it is the very first time this script is
run, and therefore run HDClean only once.

3.3.4. Synchronizing instead of RestoreDiskImage


You can greatly improve the speed of the restoration process by avoiding to remove
all files before restoring an archive. If the partition contains files, REMBO will
attempt to synchronize the content of the partition with the disk image, rather than

58
Chapter 3. OS-Specific Instructions
blindly restoring everything. If most of the files on the partition have not changed
between two restorations, the synchronize mode will be much faster than a blind
restoration. Here is an example of synchronization script:
// Step 1. 1.5GB NTFS partition
SetPrimaryPartitions(0,"NTFS:1500000");

// Step 2.
Synchronize("cache://global/hdimages/winnt/baseimage.img",
"disk://0:1","b");

// Step 3. Name is based on the last bytes of


// the hardware address
var hwa = StrParse(NetInfo.MACAddress," ");
str name = "NTRBO-"+hwa[4]+hwa[5];
NTChangeName(name);

// Step 4.
HDBoot(0,1);

See the Synchronize manual page for more information about different
synchronization modes.
If the partition is corrupted because Windows NT was powered off without using
the shutdown sequence, the synchronize mode of REMBO might fail because of
corrupted files. You can implement fail-safe restoration by formatting the hard disk
if synchronize fails to restore the image. The following example uses an exception
handler to trap synchronize errors and clean the partition:
str imgname = "cache://global/hdimages/winnt/baseimage.img");
var SyncErrorHandler(var exc)
{
Log("Restoration failed. Rebooting<br>");
// Clean the partition
DeviceCleanEx("disk://0:1",DeviceGetInfo(imgname));
// Wait 2 secs
delay(200);
// Reboot the computer to go in a safe state
Reboot();
}
// Synchronize:
with (SyncErrorHandler) try {
Synchronize(imgname,"disk://0:1","b");
}
Log("Restoration successful<br>");

Note the use of DeviceCleanEx instead of HDClean, as described in Section 2.3.3.

59
Chapter 3. OS-Specific Instructions
3.3.5. Customizing
The target computer customization is a very important phase of the cloning process.
This phase sets custom parameters into the Windows NT workstation to prevent
conflicts due to the fact that all cloned computer have the same name or the same IP
address.
In Windows NT, all parameters reside in a single location, the Windows NT
registry. Practically, the registry is stored in several files: SAM, SOFTWARE, SYSTEM,
SECURITY and DEFAULT. These five files are stored in the same directory, namely
/WINNT/system32/config, /WINDOWS/system32/config on Windows XP.

Use NTSetPartition and NTDetect() in your script, just after having restored the
image on the hard-disk, to tell REMBO where Windows NT has been restored. This
will make sure that high-level NT functions like NTChangeName or NTJoinDomain
works all the time.
To change the hostname of the computer, you can use the wizards or one of the
high-level Rembo-C functions like NTChangeName. See Section 5.5 in Rembo-C
Scripting Reference Manual for more information.
If you want to modify a specific registry key, use the following procedure:

1. Under Windows NT, run REGEDT32 and locate the parameter you want to
change. Computer settings are stored in HKLM/System/ControlSet001.
2. Determine in which file your parameter is located. HKLM/Software keys are
stored in SOFTWARE, HKLM/System keys are stored in SYSTEM, HKLM/Security
keys are stored in SECURITY, HKLM/SAM keys are stored in SAM and the
default user profile is stored in DEFAULT.
3. Create a script that opens the registry file, modify the value as described in the
reg: URL manual page and closes the registry.

Here is an example script for changing the username displayed in the Windows NT
logon dialog:
// the winlogon key is in the software registry
OpenRegistry("soft","disk://0:1/winnt/system32/config/software");
// save the value (unicode string) in the DefaultUserName key
// the string spans several lines because of printing limitations
// you can write the same command in one single line
CreateUnicodeFile("reg://soft/Microsoft/"
"Windows NT/CurrentVersion/"
"Winlogon/DefaultUserName",
"Sample user");
// Close the registry to commit change
CloseRegistry("soft");

60
Chapter 3. OS-Specific Instructions

You can add your customization scripts at the end of your restoration script, just
before booting on the partition.

3.3.6. Incremental images (TextDiff)


Incremental images let you create images of operating system applications, and
restore these application packages in conjunction with a base image. The advantage
of incremental images over one single base image is that you can decide which
application you want to include in a deployment process on a case by case basis.
Incremental images for Windows NT/2K/XP are created using two functions,
TextDiff and MakeDiffFromText. Toolkit wizards offer you a very easy and
interactive way to create incremental images using TextDiff and
MakeDiffFromText. The paragraph below show you the manual way to perform the
same action.
Here is the procedure to follow to create an advanced incremental image:

1. Restore the base image on a workstation (with no additional incremental


image). This is is called the original state.
2. From this safe state, boot and install the required software. The computer will
be in the final state. The goal of an incremental image is to contain all the
differences between the original state and the final state, so that it is possible to
regenerate the final state from the original state.
3. Create an incremental log by calling TextDiff.
4. Review the incremental log on the server, and remove lines not required for
your application package (i.e. changes made by the operating system but not
related to the application installation).
5. Create an incremental image from the log by calling MakeDiffFromText.

Here are the details on how to call TextDiff to create the incremental log and
MakeDiffFromText to create the incremental image.

When your software is installed (point 2 of the procedure), prepare a folder on your
server to store the incremental image files. Start REMBO and run the following
script.
// It is assumed that:
// - the OS is on disk://0:1
// - the base image is cache://global/baseimage
// - the incremental folder is cache://global/mydiff/
TextDiff("disk://0:1",
"cache://global/baseimage",

61
Chapter 3. OS-Specific Instructions
"cache://global/mydiff/mydiff.log",true);

Then, after having modified the file mydiff.log on the server, the following script
creates the incremental image files. MakeDiffFromText creates several files: one for
the files (.fil) and one for each registry hive (.sof,.sys,...).
// It is assumed that:
// - the OS is on disk://0:1
// - the base image is cache://global/baseimage
// - the incremental folder is cache://global/mydiff/
MakeDiffFromText(
"disk://0:1",
"cache://global/baseimage",
"cache://global/mydiff/mydiff.log",
"cache://global/mydiff",true);

Now that your incremental image is created, read the next section to learn how to
restore it.

3.3.6.1. Restoring an incremental image


Restoring an incremental image is performed with the ApplyDiff function. This
function has to be called after the operating system has been restored on the hard
disk.
Restoring an incremental image is made of two steps:

1. Restore the files;


2. Apply registry changes.

Here is a complete example of restoration, with inline comments to clarify


individual steps:
// Step 1. Restore base image
RestoreDiskImage(0,1,"cache://global/baseimage");

// Step 2. Apply incremental image


// you can repeat this step for each of your software packages
ApplyDiff("cache://global/mydiff","disk://0:1",true);

... customize hostname and boot

62
Chapter 3. OS-Specific Instructions
3.3.7. Patching NT SID with REMBO
This section shows a step-by-step guide on how to replace the SID on a NTFS
partition and in NT registry files.
Please refer to your Microsoft documentation to decide whether you really need to
change the SID or not when cloning NT workstations. If all NT workstations are
domain members, and all users are created on the domain controller, then you
would probably prefer not to change the SID (i.e. use the SID on all workstations).
REMBO provides a binary and textual SID replacement tool similar to what other
vendors offer. Please note that if you want to change the SID in a supported and
standard way, you should use the SysPrep utility available from Microsoft.
Here are the actions to perform in order to generate a unique SID for target
computers. In this example, we show how to restore the NTFS disk image stored in
cache://global/ntbase.img to the first partition, using the on-the-fly SID
replacement routines of REMBO. In addition, we also show how to save the
generated SID in a host specific file to reuse this SID on later restorations.

1. Extract original SID from the hard disk image, and store in the binary variable
oldsid.
OpenArchive("nt","cache://global/ntbase.img");
var oldsid =
GetSIDFromRegistry("arch://nt/winnt/system32/config/sam");
CloseArchive("nt");

2. Generate an unique SID for this host, or use the SID stored in the file
net://host/SID. Store this new SID in the binary variable newsid.
var newsid;
if (!FileExists("net://host/SID")) { // no stored SID
newsid = GenerateSID(oldsid); // generate
CreateHexFile("net://host/SID",newsid); // store
} else {
// use stored SID
newsid = LoadHexFile("net://host/SID");
}

3. Restore the disk image (you can remove HDClean if you want to perform a
synchronization instead of full-restore).
HDClean(0,1);
// set SID on-the-fly replacement parameters
ApplySID("disk://0:1",oldsid,newsid);
// restore/synchronize image
Synchronize("cache://global/ntbase.img",
"disk://0:1","b");

63
Chapter 3. OS-Specific Instructions
4. Replace SID in registry files.
PatchSID(oldsid,newsid);

Here is the complete script:


OpenArchive("nt","cache://global/ntbase.img");
var oldsid =
GetSIDFromRegistry("arch://nt/winnt/system32/config/sam");
CloseArchive("nt");
var newsid;
if (!FileExists("net://host/SID")) { // no stored SID
newsid = GenerateSID(oldsid); // generate
CreateHexFile("net://host/SID",newsid); // store
} else {
// use stored SID
newsid = LoadHexFile("net://host/SID");
}
DeviceCleanEx("disk://0:1",
DeviceGetInfo("cache://global/ntbase.img"));
// set SID on-the-fly replacement parameters
ApplySID("disk://0:1",oldsid,newsid);
// restore/synchronize image
Synchronize("cache://global/ntbase.img",
"disk://0:1","b");
PatchSID(oldsid,newsid);

Please read the reference pages in Section 5.5 in Rembo-C Scripting Reference
Manual for more details on each of the SID specific functions.

3.4. Cloning Linux

3.4.1. Creating a Linux base image


The first step of the creation of the reference disk image is the reference computer
preparation. Prepare your reference computer by installing a linux distribution from
scratch and customize your linux distribution to your needs. Whenever possible, try
to install all the distribution on a single partition, in order to make image creation
easier. If you want to use multiple partitions on the reference and the target
computer, then you will have to create multiple base images (one image per
partition).
During the preparation of the reference disk image, you will have to choose
between two alternatives:

64
Chapter 3. OS-Specific Instructions
1. Have a complete linux distribution on the reference disk image, thus creating a
very large reference image. Be aware that this large image can take some time
to restore.
2. Copy some parts of the distribution (for example /usr) on a NFS server and
remove these parts from the reference partition. This will create smaller
images, but the resulting linux workstation will have reduced performance due
to NFS accesses at runtime.

When your reference workstation is ready, use the following script to create the
base image. If you have multiple partitions, repeat the steps for each partition:
// Create an image of partition 1 (/dev/hda1)
BuildDiskImage(0,1,"cache://global/hdimages/linux/baseimage.base");

If you have multiple partitions and you want to create only one base image
containing the data from all partitions, you must use a virtual image to merge the
partitions together in a virtual filesystem. The following example assumes that the
root partition is /dev/hda1, /dev/hda5 is /usr, and /dev/hda6 is /home.
// Step 1. Create a virtual image with the root partition (hda1)
CreateVirtualImage("linux","disk://0:1");

// Step 2. Add /usr to the virtual image (hda5)


LinkTree("link://linux/usr","disk://0:5");

// Step 3. Add /home to the virtual image (hda6)


LinkTree("link://linux/home","disk://0:6");

// Step 4. Create a disk image of the virtual image


Synchronize("link://linux",
"cache://global/hdimages/linux/baseimage.base","");

You do not need to make an image of your swap partition, because the swap
partition does not contain any valuable data, and it can be created dynamically by
REMBO on startup.

3.4.2. Linux kernel booting


The next step of the linux cloning is testing your reference image on a new
workstation. But before that we would like to describe how to start a linux kernel,
because the test phase needs to start a linux kernel.
Use the LXBoot function to start a linux kernel. The first parameter is the filename
containing the kernel image, and the third parameter contains the kernel parameters

65
Chapter 3. OS-Specific Instructions
to be passed to linux. The kernel image must be in zImage or bzImage format. These
two format are the standard kernel image formats used by kernel source makefiles.
You do not need to tag kernel images to use them with REMBO. The second
parameter of LXBoot, the initial ramdisk, is not used in this description.
In order to use LXBoot, you must extract the kernel file from your hard disk. You
can use the Professional or Enterprise wizards to do this action, or do it manually by
copying the kernel file on the server (with CopyFile). Kernel images are usually
stored in /boot. The following script example assumes that /boot is in the root
partition hda1:
CopyFile("disk://0:1/boot/vmlinuz",
"cache://global/hdimages/linux/basekernel.krn");

The following example shows how to start your kernel image with the root
filesystem installed on /dev/hda1:
LXBoot("cache://global/hdimages/linux/basekernel.krn",
"","root=/dev/hda1");

3.4.3. Testing the base disk image


We recommend that you test your reference image on a separate workstation before
deploying it to multiple workstations or before modifying your reference
workstation. When your reference image is successfully tested, you can use it as a
backup for your reference workstation if something goes wrong in subsequent steps
of the cloning.
Run REMBO on a new workstation, and create your partitions as needed. Do not
forget to create a swap partition. Then restore the image you created in the previous
section with RestoreDiskImage. The following script shows how these functions
should be called:
// Step 1. Create 800MB for one linux partition,
// and 128MB for swap
SetPrimaryPartitions(0,"EXT2:800000 EXT:128000");
SetLogicalPartitions(0,"LINUX-SWAP:128000");

// Step 2. Restore the base image


RestoreDiskImage(0,1,"cache://global/hdimages/linux/baseimage.base");

// Step 3. Setup the swap partition


HDClean(0,5);

// Step 4. Launch the kernel


LXBoot("cache://global/lxkernel","","root=/dev/hda1");

66
Chapter 3. OS-Specific Instructions

It is important to understand that the only way to boot your restored linux image is
through a call to LXBoot. If you try HDBoot(0,1);, this would certainly fail because
the files required by the linux boot loader LILO have been moved during the
restoration.
You can then use this script as your restoration script for linux computers. If you
want to execute this script at startup time, copy the script content in the <script> tag
of an empty HTML page, and set the server parameter StartPage to refer this
HTML page.

3.4.4. Creating a restoration script


You can use the script created in the previous section for restoring linux hard disk
images. This script uses RestoreDiskImage to install the hard disk image on the
disk. This function always perform a full restore of the disk image.
You can use Synchronize to achieve the same functionality as BuildDiskImage, but
without formatting the target partition. When the partition already contain files,
Synchronize builds a list of differences between the base image and the files on the
disk and copy only the files that need to be restored (and delete only the files that
need to be deleted). This process is much more faster than BuildDiskImage if only
a few files are modified between subsequent restorations.
If you have opted for synchronization rather than full restoration, you have to take
into consideration that if the partition is corrupted (e.g. the computer was not
shutdown properly), Synchronize may fail to restore the disk image. To handle this
situation (i.e. to create a fail-safe synchronization procedure), you can use an
exception handler to catch errors generated by Synchronize. If an error occurs,
simply format the target partition and reboot. This will return to REMBO in a safe
state and Synchronize will be able to restore all the files.
Here is a sample script to implement fail-safe synchronization:
// Exception handler
var SyncErrorHandler(var exc)
{
Log("An error has occured. Rebooting...<br>");
// Format the target partition
HDClean(0,1);
// Wait 2 secs
delay(200);
// Reboot
Reboot();
}
// Synchronization
with (SyncErrorHandler) try {

67
Chapter 3. OS-Specific Instructions
Synchronize("cache://global/hdimages/linux/baseimage.base",
"disk://0:1","b");
}

3.4.5. Linux Incremental images


To create an incremental image for your linux base image, simply run Synchronize
in incremental mode. Here is an example:
// Create an incremental image between the current disk content
// and the base image
Synchronize("disk://0:1",
"cache://global/hdimages/linux/baseimage.base",
">cache://global/hdimages/linux/mysoft.diff");

To restore this incremental image, use a virtual image to merge the base image with
the incremental image. Here is an example:
// Step 1. Open the disk archives
OpenArchive("base","cache://global/hdimages/linux/baseimage.base");
OpenArchive("diff","cache://global/hdimages/linux/mysoft.diff");

// Step 2. Create a virtual image on the base image


CreateVirtualImage("lx","arch://base");

// Step 3. Merge the incremental image in the virtual image


LinkTree("link://lx","arch://diff");

// Step 4. Synchronize the virtual image with the disk


Synchronize("link://lx","disk://0:1","b");

// Step 5. Free ressources


FreeVirtualImage("lx");
CloseArchive("diff");
CloseArchive("base");

3.4.6. Customizing Linux startup scripts


Usually, Linux workstations do not need as much customization as Windows
workstations, because Linux workstations are better integrated for a network
infrastructure.
To reduce your customization needs to a minimum, configure your reference image
with automatic network configuration using DHCP, and add a command in your

68
Chapter 3. OS-Specific Instructions
/etc/rc.d/rc.local (or similar) startup script to execute a script located on the
server. This script can then perform tasks based on the IP address of the local
workstation (given that you have stored the local IP address in a environment
variable).
If you use the authentication features of REMBO, you can use the information
collected during the authentication (the username and eventually the password) to
drive your linux startup scripts (for example you could start X automatically with a
command like su -l -c startx $username. Use the PatchFile function to
create a script setting the $username linux variable.
Example 3-2. Starting X based on the username

chown $username /dev/console /dev/fd0


chmod 622 /dev/console
su -l -c startx $username

69
I. REMBO URL types reference
Table of Contents
Disk URLs............................................................................................................... 72
Floppy URLs .......................................................................................................... 75
CDROM URLs ....................................................................................................... 77
Ramdisk URLs ....................................................................................................... 79
Net URLs................................................................................................................. 81
Cache URLs............................................................................................................ 85
Reg URLs................................................................................................................ 87
Arch URLs .............................................................................................................. 90
Diff URLs................................................................................................................ 91
Link URLs .............................................................................................................. 93
Display URLs.......................................................................................................... 95
Loopback URLs ..................................................................................................... 98
Variable URLs ...................................................................................................... 100
REMBO URL types reference
Disk URLs
Disk URLs — Hard disk access
Synopsis
disk://disknum:partnum/path

disk://disknum:partnum:fstype/path

Description
Files and directories stored on local partitions are accessed through disk URLs.
Such a URL uniquely describes the location of a file in the local computer. The root
device contains the disk number and the partition index on which the file can be
found.

Root device format

disknum

The disknum part of the root device is the numerical index of the local hard
disk containing the file described by the URL. Hard disks are numbered from
0, that is, the first hard disk is hard disk 0.

partnum

This is the index of the partition where the file is located. First partition is
number 1. If you have extended partitions, indexes for partitions embedded in
an extended partition will start after the last index of the current partition table.
For example, if partition 2 is an extended partition containing two
sub-partitions (logical drives), the two logical drives will be found at indexes 5
and 6 (since indexes 1 to 4 are used by the primary partition table). And if one
of these logical drives is also an extended partition, its embedded logical drives
will be found at indexes 9 and follow (indexes 5 to 8 being used by the
extended partition 2).
The partition number 0 has a special meaning. It points at the master partition
table. You can use partition 0 to manipulate the master partition table (add,
delete or modify partitions), since REMBO provides a virtual file system
giving you access to the partition table as a standard file.
The partition number -1 is the cache partition. REMBO uses the unpartitioned
space at the end of the disk as a cache for network files. When you open a
remote file with a URL starting with the prefix cache://, a copy of the remote
file will be made on the local cache partition (if such a partition exists) and
REMBO will access the file through the local copy. See the cache URL for
more information.

72
Disk URLs

fstype

The fstype parameter is optional. It can be used to tell REMBO which


filesystem to use when opening the URL. If this parameter is omitted, REMBO
will look at the partition type value located in the partition table and will
determine which filesystem to use based on this value. REMBO supports the
following filesystem tags:

• FAT16: the FAT filesystem with a 16-bits file allocation table. Used by
MS-DOS and all Windows operating systems. Is limited to 2048Mb.
• FAT12: the FAT filesystem with a 12-bits file allocation table. Used on
floppies only.
• FAT32: the FAT filesystem with a 32-bits file allocation table. Used by
Windows 98 and Windows 2000. This filesystem outpasses the 2048Mb
limit of FAT16.
• EXT2FS: the second extended filesystem. Used by the Linux operating
system.
• NTFS: Windows NT filesystem. Supported by Windows NT and Windows
2000.
• SWAPFS: the SWAP filesystem. Used on swap partitions by the Linux
operating system. This filesystem is supported by REMBO in order to allow
the creation of SWAP partitions for Linux.
• CACHEFS: REMBO cache filesystem. This is the filesystem used by
REMBO to store files in the cache partition. It can only be used on partition
-1.
• MBRFS: Master Boot Record filesystem. This is a virtual filesystem created
by REMBO to provide an interface for modifying partition tables. It can
only be used on partition 0 and on extended partitions.

Examples

The file /windows/win.ini on the first partition of the first disk is denoted by
disk://0:1/windows/win.ini

73
Disk URLs
The master partition table is denoted by
disk://0:0/PartitionTable

The directory global on the cache partition is denoted by


disk://0:-1/global

The file test.dat on the first logical drive of an extended partition defined in the
master partition table of the second disk is denoted by
disk://1:5/test.dat

See also
floppy://
cdrom://

74
Floppy URLs
Floppy URLs — Floppy disk access
Synopsis
floppy://floppynum/path

floppy://floppynum:fstype/path

Description
The floppy disk URL is similar to the hard disk URL. Both URL handlers are used
to access files on a local device. But as floppy disks do not have partitions, the
filesystem type cannot be determined from the partition information. It must be
either autodetected or specified by the user.

Root device format

floppynum

This is the index of the floppy disk. Most systems have only one floppy disk
drive, in which case this parameter will always be 0. If you have several floppy
disk drives, they are numbered from 0 to n-1, where n is the number of
installed floppy disk drives.

fstype

This is an optional parameter. If you specify a fstype (filesystem type), it will


be used by REMBO when accessing files on the floppy. The valid values for
fstype are the same as for the disk:// URL type.
If you omit this parameter, REMBO will try to autodetect the filesystem stored
on the floppy. If the detection fails, REMBO will select the RAWFS filesystem,
which consists of a virtual filesystem containing a file for direct access to bytes
stored on the floppy.

Examples

The file test.dat on the first floppy is denoted by


floppy://0/test.dat

75
Floppy URLs
The file test.dat on the first floppy, with the assumption that the filesystem on the
floppy is FAT12, is denoted by
floppy://0:FAT12/test.dat

See also
disk://
cdrom://

76
CDROM URLs
CDROM URLs — CD-Rom disk access
Synopsis
cdrom://cdnum:cdpart/path

cdrom://cdnum:cdpart/path

Description
The CDROM URL is used to access files stored on a CDROM. Your BIOS must
contain support for booting on a CD, and CD access through BIOS calls (el Torito
specification).

Root device format

cdnum

This is the index of the CD-Rom drive. Current version of REMBO only
support one CD-Rom drive, and therefore this parameter should always be 0.

cdpart

This part of the URL is used to specify which part of the CD to access. If
cdpart is 0, Rembo will try to access the Rembo bootable image stored on the
CD, if any. To access the actual content of the CD (as under Linux or
Windows), cdpart must be set to 1.

Examples

The file autoload on a REMBO bootable CD is denoted by


cdrom://0:0/autoload

The file diskimage.img copied on an ISO9660 CD can be referred as


cdrom://0:1/diskimage.img

77
CDROM URLs
See also
floppy://
disk://

78
Ramdisk URLs
Ramdisk URLs — Ramdisks access
Synopsis
ram://ramdisk/path

ram://ramdisk:fstype/path

Description
The ram URL handler can be used to access files or directories stored on a ramdisk
created with CreateRamDisk or LoadRamDisk scripting functions. It is an adequate
way to customize ramdisks before booting on it.
Ramdisks, like floppy disks, do not have partitions. They thus share the same root
device format.

Root device format

ramdisk

This is the index of the ramdisk described by the URL. This index must match
an existing ramdisk.

fstype

This parameter is optional, and has the same meaning as for floppy:// URLs.
If this parameter is ommited, REMBO tries to autodetect the filesystem.

Examples

The file test.dat on the ramdisk is denoted by


ram://0/test.dat

The file test.dat on the ramdisk, assuming that the filesystem on the ramdisk is
EXT2FS, is denoted by
ram://0:EXT2FS/test.dat

79
Ramdisk URLs

See also
disk://
floppy://
var://

80
Net URLs
Net URLs — Remote files access
Synopsis
net://global/path

net://group/path

net://host/path

net://user/path

net://a.b.c.d/path

Description
The net:// URL refers to files stored on a remote REMBO file server. A REMBO
file server offer read and write access to its files through the NETfs protocol. NETfs
is an UDP unicast protocol. Several root devices are defined. They map to a
different locations on the default REMBO server, or can specify an arbitrary file
server by its IP address.
The first four root devices point to locations in the default REMBO server
filesystem. The default REMBO server is usually the server from which the host has
received its network boot parameters. To be exact, the default server is the host
specified in the FileServer parameter of the NBPServer section of the
rembo.conf file.

Root device format

global

The global root device refers to the root directory of the file server. Every file
on the default file server can be located using the global root device. Use this
root device when you want to access files shared among all remote-boot
clients.
group, host and user all refer to subdirectories of the file server, and can
therefore be accessed using the global root device by adding the adequate
subdirectory prefix.

group

The group root device corresponds to a location specific to a group of hosts.


All hosts in a common group will see the same files when accessing the group
root device, but hosts belonging to an other group will not see the same files.

81
Net URLs
Groups are defined in the server configuration file by adding a group statement
in the NBPServer section. If a host is not defined in any group, it will
automatically join the default group.
You can access files stored in other group root devices using the global root
device, by adding /groups/groupname/ in front of the filename to access.
Replace groupname by the name of the group to access.
Group-based root device is adequate for storing group specific files. For
example, you can store hard disk images on a group root device, because hard
disk images are often specific to a group of host. If the disk image is used by
all hosts of all groups, then use the global root device instead.

host

Use the host root device to access files located in a directory specific to each
client host running REMBO. Every client has its own directory on the file
server, which can be accessed using a uniform URL. As for group-based root
device, host-based root devices can be accessed through the global root device
by adding /hosts/hwaddr in front of the filename to access (hwaddr must be
replaced by the hardware address of the host to access. For example, if the
hardware address is 00:90:27:12:1a:14, the prefix will be
/hosts/009027121a14/.

Use the host URL type for storing files specific to the host running REMBO.
For example, image differences (hard disk images containing files to add to an
existing filesystem) containing host-specific files can be stored in the
host-based root device. The image difference file can be (and will probably be)
different for each host, but scripts will all refer to net://host/diff.img.

user

Use the user root device to access files on a user-based scheme. Files
accessed from a user-based URL will be specific to the logged in user. This
kind of URL can only be used after a successful Logon or LogonUser (or
AuthUser) scripting function call. As for group and host files, user-based files
can be access through the global root device by adding the /users/username/
prefix (replace username with the name of the user to access).
You can use user-based root devices to store user specific settings, such as
graphical interface default choices. You can also use user-based files to store a
profile describing the applications selected by the user. The user could then
have its own applications installed on a computer, regardless of the computer
he has logged on.

82
Net URLs

a.b.c.d

The a.b.c.d root device (where a.b.c.d is a valid IP address) can be used to
access a REMBO server which is not the default server. The IP address must
corresponds to a running REMBO server with the NETfs file service enabled.
For example, net://192.168.10.15/test.dat is the URL for the file
/test.dat on the REMBO file server at IP address 192.168.10.15.

Examples

The file test.dat located at the root of the default server is denoted by
net://global/test.dat

The group-specific file testdir/test.dat, assuming that the client host belongs to
the rembotest group, is denoted by
net://group/testdir/test.dat
This file can also be located by the following URL:
net://global/groups/rembotest/testdir/test.dat

The file test.dat in the host directory, assuming that the client hardware address is
00:90:27:d1:43:44, is denoted by
net://host/test.dat
This file can also be located by the following URL:
net://global/hosts/009027d14344/test.dat

The user-specific file test.dat assuming that the user logged in is john, is denoted
by
net://user/test.dat
This file can also be located by the following URL:
net://global/users/john/test.dat

The file test.dat located on the server 192.168.12.13 is denoted by

83
Net URLs
net://192.168.12.13/test.dat

See also
cache://

84
Cache URLs
Cache URLs — Network access through the local partition
Synopsis
cache://global/path

cache://group/path

cache://host/path

cache://user/path

cache://a.b.c.d/path

Description
The cache URL type is a front-end to access net URLs. It refers to the same files,
and thus uses the same root device format and meaning. However, when a remote
file is accessed through a cache URL, the file will be first downloaded to the local
cache partition and then be opened locally. Using cache URLs instead of net URLs
greatly improves performance, since remote files are cached on the local hard disk.
To benefit from this feature, you must activate a local cache partition on the hard
disk of the REMBO client. To do so, leave some unpartitioned space at the end of
the client hard disk (i.e., ensure that the last partition ends before the end of the hard
disk, thus leaving a part of disk unpartitioned). REMBO will transform this space
into a local cache partition on the first access to a disk://0:-1/ URL. Once the
local partition is activated, files accessed through a cache URL will be transferred
to the local cache with the MCAST file transfer protocol. This protocol uses the
multicast technology, allowing the simultaneous transfer to multiple hosts without
using more bandwidth than for a single host. Whenever the file changes on the
server, REMBO will automatically download the new version of the file to the local
cache, thus guaranteeing that the local cached copy is always up-to-date with its
reference file on the server.
Files written to cache: are transferred to the server using the FAST protocol. This
protocol is a UDP unicast protocol faster than NETfs.

If the local cache partition is not activated, cache will act as a net URL type. All
requests will be transparently forwarded to the file server.
It is recommended to use cache URLs for all remote files. This will spare network
bandwidth, and greatly improve the overall performance of REMBO (protocols
used for cache: are faster then protocols used for net: if a local cache partition
exists). In particular, it is strongly recommended to use cache URLs when
accessing hard disk images stored on the server. A disk image can quickly gets
larger than 100MB, and if multiple hosts are restoring an image ar the same time,
there is a high probability that the network becomes saturated. The cache

85
Cache URLs
mechasisms avoid reloading disk images unnecessarily. Furthermore, in opposition
to NETfs files, cached files are downloaded using a multicast protocol. That means,
when several machines download a large file to their local cache at the same time,
they will reuse the same network bandwidth.
If hard disk image restoration is to be performed frequently, then cache URLs will
dramatically improve overall performance. The hard disk image will be fetched
from the local disk, at a higher speed than over the network. The overall time
needed to restore an image may typically fall from 15 minutes to 2 minutes by using
cache URLs on a 200MB disk image.

Root device format


Since the cache URL type is a front-end to access net URLs, you will find a
complete description of valid root devices in the net:// documentation.

Example

The file win2k.img can be accessed through the local cache by using the following
URL:
cache://global/win2k.img

See also
net://

86
Reg URLs
Reg URLs — Windows NT registry access
Synopsis
reg://registry/path

Description
The reg filesystem is used to access Windows NT (NT4 and Win2K) registries
internally from REMBO. Before using a reg, you must open a Windows NT
registry file with the OpenRegistry scripting function.

When the registry processing is finished, do not forget to close the registry
with the CloseRegistry scripting function.
Directories in a registry correspond to the keys shown in the left part of a Windows
regedit dialog box. And files are the values shown in the right part of a Windows
regedit dialog box. The extension of files is determined by the data type of the
value. Table 1 shows the list of extensions defined in REMBO.
Table 1. Supported registry types

.unicode A unicode string (REGSZ), use


CreateUnicodeFile and
LoadUnicodeFile to manipulate this
data type.
.multiuni Multiple unicode strings separated by
0x0000 (REGMULTI), use
CreateMultiUniFile and
LoadMultiUniFile to manipulate this
data type.
.expuni A unicode string with variable
expansion (EXPSZ), use
CreateUnicodeFile and
LoadUnicodeFile to manipulate this
data type.
.dword An unsigned 32-bits value in big-endian
order (REGDWORD), use
CreateBinaryFile and
LoadBinaryFile to manipulate this data
type (see example below).

87
Reg URLs

.binary An array of binary octets (REGBIN),


use CreateBinaryFile and
LoadBinaryFile to manipulate this data
type (see example below).
.unknown Unsupported data type (to be considered
as binary)

Root device format

registry

This is the name of the registry as previously given to the OpenRegistry


scripting function. You can access multiple registries concurrently by
assigning to each registry a different name.

Example

The value of Version (unicode string), in the key /Software/Microsoft/DirectX


of the the open registry test, is denoted by
reg://test/Software/Microsoft/DirectX/Version.unicode

To modify the value /Software/Microsoft/DirectX/Version, use


OpenRegistry("test","disk://0:1/winnt/system/config/software");
CreateUnicodeFile(
"reg://test/Software/Microsoft/DirectX/Version.Unicode",
"NEWVALUE");
CloseRegistry("test");

If the value is a DWORD, use


CreateBinaryFile("reg://test/sample.dword",BinFromInt(value));
int value = BinToInt(LoadBinaryFile("reg://test/sample.dword"));

If the value is BINARY, use


str hexvalue = "0A5687FEABABAB";
CreateBinaryFile("reg://test/sample.binary",FromHex(hexvalue));
str value = ToHex(LoadBinaryFile("reg://test/sample.binary"));

88
Reg URLs

89
Arch URLs
Arch URLs — REMBO disk image archive (read-only access)
Synopsis
arch://archive/path

Description
Use the arch filesystem to browse or restore the content of a disk image archive.
Before using an arch URL, you must open the archive with the OpenArchive
scripting function.

When archive processing is finished, do not forget to close the archive using
the CloseArchive scripting function.
Disk image archives can only be read using arch URLs. To change the content of an
archive, you must use REMBO’s synchronization mechanism (see Synchronize).

Root device format

archive

This is the name of the archive as previously given to the OpenArchive


scripting function. You can open several archives concurrently by assigning to
each of them a different name.

Example

The directory /windows in an archive opened under the alias wininstall is denoted
by
arch://wininstall/windows

See also
link://

90
Diff URLs
Diff URLs — REMBO local disk image (read-only access)
Synopsis
diff://archive/path

Description
This URL is similar to arch, with the difference that it operates on local disk
images (diffs) instead of normal REMBO archives. Local disk images are created
by Synchronize when the destination is not a server. The compression algorithm is
different than the one used for normal REMBO archives because compression is
performed on the client instead of the server. Before using an diff URL, you must
open the disk image with the OpenDiff scripting function.

When disk image processing is finished, do not forget to close the disk image
using the CloseDiff scripting function.
Access to disk images is read-only. If you want to change the content of the disk
image, you will have to create a new disk image.

Root device format

archive

This is the name of the disk image as previously given to the OpenDiff
scripting function. You can open several disk images concurrently by assigning
to each of them a different name.

Example

The directory /windows in an disk image opened under the alias wininstall is
denoted by
diff://wininstall/windows

91
Diff URLs
See also
arch://

92
Link URLs
Link URLs — Virtual file system
Synopsis
link://virtualname/path

Description
Use the link virtual filesystem to build a virtual disk image by grafting several
existing directories together (see the explanations below). Before using a link
URL, you must create the virtual file system with the CreateVirtualImage
scripting function.

When the virtual image processing is finished, do not forget to free the
ressources used by the virtual image using the FreeVirtualImage scripting
function.
A virtual filesystem can be seen as a workbench for temporarily putting together
directory trees, typically for the purpose of creating or restoring a disk image. A
virtual filesystem cannot store any file for itself, but can link to files and directories
taken from many different devices, including disk image archives. The resulting file
hierarchy can then be saved or restored as a whole using REMBO’s synchronization
mechanism.

Root device format

virtualname

This is the name of the virtual disk image as previously given to the
CreateVirtualImage scripting function. You can use multiple virtual images
concurrently by assigning to each of them a different name.

Example

The file /etc/dhcpd.conf in a virtual disk image named install is denoted by


link://install/etc/dhcpd.conf

93
Link URLs
See also
arch://

94
Display URLs
Display URLs — REMBO user interface
Synopsis
display://console/path

display://root/path

display://windowname/path

Description
Display URLs are used to access REMBO user interface. Each window displayed
on the screen is mapped to a root device. Each widget within a window is mapped
to a subdirectory. Each widget property is a mapped to a text file within its
subdirectory. Nested widgets are mapped to nested subdirectories.
REMBO uses HTML as native representation for all displayed objects. Two special
files are present in every directory:

• SELF is the HTML representation of the widget as a whole, including its


sub-widgets. This file can be read and modified. When the file is rewritten, the
widget is destroyed and a new content is build from the new HTML description.
• SELF-APPEND is a write-only file which act as a pipe to the end of the widget
description. Everything written in this file is appended to the description of the
widget. Note that some widgets may not support the append operation.

The remaining files and subdirectories present in each widget depend on the type of
the widget. Their number typically increases dynamically as more data is displayed
in the widget. The name of the widget properties is determined by their semantic
within the widget. The name of the subwidgets is either the name given as HTML
name attribute, or the name given as HTML id attribute, or a generic alphanumeric
name if none was provided. You may use the file manager to browse a widget
hierarchy for a given window.
Whenever a file is changed in the display filesystem, the target window is reflowed
and updated as soon as the file is closed. It is therefore much more efficient to build
a complete HTML description in a string and to write it at once to a widget than to
write it piece by piece to the SELF-APPEND file.
CSS1 Stylesheet definitions can be freely inserted in the HTML input. Consecutive
style changes are cascaded as if they were following each other on the same page.
Style sheets are global to each window, and are only cleared when the whole
window is redefined (that is, when /SELF is rewritten).

95
Display URLs
Synchronous user input can be retrieved by reading the widget content and/or
properties (typically for text input widgets and textarea widgets). Asynchronous
user input can be handled by installing event callbacks using HTML on-event
attributes (typically for buttons and menus).
An alternative to descending the widget hierarchy in the display filesystem is to
instantiate the widget variable for a given path, and to descend the hierarchy
through the variable recursive structure. For more on this topic, refer to the Widget
primitive in REMBO Programming Manual.

Root device format

root

This represents the display root, always present even when no window is
there. It always contain at least

• a file /color which contains the default background color of desktop.


• a file /menu which defines the content of the REMBO pop-up menu, always
visible on the lower left corner of the screen.
• a subdirectory /desktop/ containing the top-level widget of the desktop
display, usually a flowed text widget. You can customize the aspect of the
desktop by changing the content of this widget.

console

This special window is used by REMBO to log all system messages. Its
definition is similar to any other window (see below), but it cannot be
destroyed. Avoid accessing the console window directly.

windowname

This is the name of a user-defined window as previously given to the


OpenHTML scripting function, or as defined in a Rembo-C program. All such
windows have usually at least

• a file /title displayed in the title bar of the window. The window has no
title bar if this file is empty.
• a directory /body/ representing the scrolling pane of the widget
• two files named /body/vscroll and /body/hscroll containing a number
representing the scroll position. Changing this number scrolls the pane
accordingly.

96
Display URLs
• a subdirectory /body/content/ containing the top-level widget, usually a
flowed text widget.

Examples

The file mapped to the HTML definition of REMBO’s desktop:


display://root/desktop/SELF

The title of the text editor window:


display://textedit/title

The content of the text input in the interactive evaluation window:


display://interact/body/content/expr/value

97
Loopback URLs
Loopback URLs — Loopback devices access
Synopsis
loop://loopdev/path

loop://loopdev:fstype/path

Description
The loop URL handler can be used to access files or directories stored on a
loopback device created with CreateLoopback. The loopdev part of a loop: is the
numerical index of the loopback device. It must match an existing loopback device
(created with CreateLoopback).
Loopback devices are like floppy disks: they do not have partitions. Therefore the
root device format for loopback devices is similar to the format of floppy URLs.

Root device format

loopdev

This is the index of the loopback device described by the URL. This index
must match an existing loopback device.

fstype

This parameter is optional, and has the same meaning as for floppy:// URLs.
If this parameter is ommited, REMBO tries to autodetect the filesystem
installed on the loopback device.

Examples

The file test.dat on the loopback device 0 is denoted by


loop://0/test.dat

The file test.dat on the loopback device 0, assuming that the filesystem on the
loopback device is EXT2FS, is denoted by

98
Loopback URLs
loop://0:EXT2FS/test.dat

See also
disk://
floppy://

99
Variable URLs
Variable URLs — Variable-mapped file access
Synopsis
var://pattern/path

Description
The var URL handler can be used to access variables as if they were regular files
(or directories for compound variables).
Variable-mapped files can be used similarly to ram disks, for a faster access,
independent of any physical device. In oppositino to ram disks, variable-mapped
devices cannot be formatted and do not support all device operations. But they have
the advantage of providing a symbolic, stateless access to preloaded files, without
memory overhead.

Root device format

pattern

This is a globbing pattern (made of letters and wildcards) of variables that


should be part of the device. For instance, the pattern *Info could be used to
access most built-in system variables.

Examples

Variable-mapped files can be used for instance to preload frequently used icon files,
without the need for an explicit Ram-disk. For instance, assuming there is a small
file under net://global/images/MyIcon.rbx, it can be preloaded using the
command
MyIcon = FileLoad("net://global/images/MyIcon.rbx");
and then be used later directly from memory using
var://*Icon/MyIcon
. Such an URL can of course be used as a source href in an HTML page.

One can browse some system information variables using the following command:
FileMan("var://*Info");

100
Variable URLs

See also
ram://

101
II. LicenseInfo built-in variable reference
Table of Contents
LicenseInfo.EndUser ........................................................................................... 104
LicenseInfo.Reseller............................................................................................. 105
LicenseInfo.Version.............................................................................................. 106
LicenseInfo.Build ................................................................................................. 107

LicenseInfo contains information about the licensed user and the REMBO product.

102
LicenseInfo built-in variable reference
LicenseInfo.EndUser
LicenseInfo.EndUser — REMBO End User name
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str LicenseInfo.EndUser

Description
This variable contains the name of the REMBO End User. This is the name of the
licensee, as printed in the about box.

104
LicenseInfo.Reseller
LicenseInfo.Reseller — Reseller name if REMBO was purchased through
a reseller
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str LicenseInfo.Reseller

Description
This variable contains the name of the REMBO Reseller who has sold this product.
This value is only valid if you have purchased REMBO from a reseller.

105
LicenseInfo.Version
LicenseInfo.Version — REMBO version string
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str LicenseInfo.Version

Description
This variable contains the version information of REMBO. Possible values are

• "2.0 Classic"

• "2.0 Pro"

• "2.0 Enterprise"

• "2.1 Toolkit"

106
LicenseInfo.Build
LicenseInfo.Build — REMBO build number
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str LicenseInfo.Build

Description
This variable contains the build number of REMBO. This is a three digits number
identifying the different releases of REMBO.

107
III. NetInfo built-in variable reference
Table of Contents
NetInfo.MACAddress .......................................................................................... 110
NetInfo.IPAddress................................................................................................ 111
NetInfo.SubnetMask ............................................................................................ 112
NetInfo.DefaultGateway...................................................................................... 113

NetInfo contains information about the local network configuration.

108
NetInfo built-in variable reference
NetInfo.MACAddress
NetInfo.MACAddress — Network interface hardware address
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str NetInfo.MACAddress

Description
This variable contains the hardware address of the REMBO. host. This hardware
address is directly read from the network card, using the PXE bootrom
programming interface.
NetInfo.MACAddress is a string representing the six bytes of the hardware address
in hexadecimal, separated with spaces.

110
NetInfo.IPAddress
NetInfo.IPAddress — Network interface IP address
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str NetInfo.IPAddress

Description
This variable can be used to retrieve the IP address of the REMBO host.
You can access this variable as a string to get the textual representation of the IP
address, or as an integer, to get the 32 bits numerical value corresponding to the IP
address in network order.

111
NetInfo.SubnetMask
NetInfo.SubnetMask — Network interface subnet mask
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str NetInfo.SubnetMask

Description
This variable can be used to retrieve the IP subnet mask of the REMBO host.
You can access this variable as a string to get the textual representation of the subnet
mask, or as an integer, to get the 32 bits numerical value corresponding to the
subnet mask in network order.

112
NetInfo.DefaultGateway
NetInfo.DefaultGateway — Default gateway IP address
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str NetInfo.DefaultGateway

Description
This variable can be used to retrieve the IP address of the default gateway. The
default gateway is the address used for sending packets to hosts not located on the
same IP subnet as the REMBO host. host.
You can access this variable as a string to get the textual representation of the IP
address, or as an integer, to get the 32 bits numerical value corresponding to the IP
address in network order.

113
IV. HostInfo built-in variable reference
Table of Contents
HostInfo.RemboServer ........................................................................................ 116
HostInfo.RemboBackupServer ........................................................................... 117
HostInfo.FileServer.............................................................................................. 118
HostInfo.FileBackupServer................................................................................. 119
HostInfo.GroupName .......................................................................................... 120
HostInfo.HostID ................................................................................................... 121
HostInfo.StartPage............................................................................................... 122
HostInfo.AdminMode .......................................................................................... 123

HostInfo contains information about parameters received from the REMBO server.

114
HostInfo built-in variable reference
HostInfo.RemboServer
HostInfo.RemboServer — REMBO server IP address
Synopsis

Variable information
Type-protected variable.

Variable declaration
str HostInfo.RemboServer

Description
This variable contains the IP address of the REMBO server used for all requests
except file transfer (default REMBO server).
You can access this variable as a string to get the textual representation of the IP
address, or as an integer, to get the 32 bits numerical value corresponding to the IP
address in network order.

116
HostInfo.RemboBackupServer
HostInfo.RemboBackupServer — REMBO backup server IP address
Synopsis

Variable information
Type-protected variable.

Variable declaration
str HostInfo.RemboBackupServer

Description
This variable contains the IP address of the REMBO backup server. All request
from client will be treated by this server when the REMBO server is not able to
answer (default "0.0.0.0", which means no backup server).
You can access this variable as a string to get the textual representation of the IP
address, or as an integer, to get the 32 bits numerical value corresponding to the IP
address in network order.

117
HostInfo.FileServer
HostInfo.FileServer — REMBO file server IP address
Synopsis

Variable information
Type-protected variable.

Variable declaration
str HostInfo.FileServer

Description
This variable contains the IP address of the REMBO file server used for file
transfers (default REMBO server)
You can access this variable as a string to get the textual representation of the IP
address, or as an integer, to get the 32 bits numerical value corresponding to the IP
address in network order.

118
HostInfo.FileBackupServer
HostInfo.FileBackupServer — REMBO file backup server IP address
Synopsis

Variable information
Type-protected variable.

Variable declaration
str HostInfo.FileBackupServer

Description
This variable contains the IP address of the REMBO file backup server. All request
from client will be treated by this server when the REMBO file server is not able to
answer (default "0.0.0.0", which means no backup server).
You can access this variable as a string to get the textual representation of the IP
address, or as an integer, to get the 32 bits numerical value corresponding to the IP
address in network order.

119
HostInfo.GroupName
HostInfo.GroupName — Current host group
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str HostInfo.GroupName

Description
This variable countains the name of the current host group. The current host group
is the group containing the host declaration for this host, or "Default" if this host is
not declared in any group and a default group is defined.
See Section 2.5 in REMBO Server Administration Manual for more information.

120
HostInfo.HostID
HostInfo.HostID — Host identifier for host urls
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str HostInfo.HostID

Description
This variable contains the Host identifier for this host. This identifier is used to
build the net://global equivalent for a net://host path.
This variable is usually set to the hardware address of the hosts, without spaces
between individual bytes.

121
HostInfo.StartPage
HostInfo.StartPage — Startup HTML page
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str HostInfo.StartPage

Description
This variable contains the path to the HTML page used by REMBO on startup. The
startpage parameter can be changed in the host group definition of the server
configuration.

122
HostInfo.AdminMode
HostInfo.AdminMode — Administrator mode flag
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
bool HostInfo.AdminMode

Description
This variable is set to true if administrator mode is enabled in the host group
definition for this host (in the server configuration). Administrative features like the
File Manager and the Interactive Evaluator are only available in administrator mode.

123
V. SystemInfo built-in variable reference
Table of Contents
SystemInfo.APM .................................................................................................. 126
SystemInfo.Disks .................................................................................................. 127
SystemInfo.Date ................................................................................................... 128
SystemInfo.BootDevice ........................................................................................ 129

SystemInfo contains information about the system and the hardware.

124
SystemInfo built-in variable reference
SystemInfo.APM
SystemInfo.APM — Advanced Power Management support flag
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
bool SystemInfo.APM

Description
This variable is set to true if Advanced Power Management (APM) is supported on
the REMBO host. If APM is not supported, the PowerOff will not be able to power
off the computer.

126
SystemInfo.Disks
SystemInfo.Disks — Hard disks sizes
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
var SystemInfo.Disks

Description
This variable is an array of integer values. Each integer value corresponds to the
size of one hard disk in kilobytes.
For example, if two hard disks are installed, SystemInfo.Disks[0] will evaluate to
the size of the first hard disk in kilobytes, SystemInfo.Disks[1] will evaluate to the
size of the second hard disk in kilobytes, and sizeof(SystemInfo.Disks); will
evaluate to 2 (2 elements in the array).

127
SystemInfo.Date
SystemInfo.Date — Current system date
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
str SystemInfo.Date

Description
This special variable contains the current system date and time. If you access this
variable as a string, you will get the textual representation of the current date and
time at the time of the variable access. If you access this variable as an integer, you
will get the date and time as the number of seconds elapsed since Jan 1st, 1970.
This value can be used for time comparisons.

128
SystemInfo.BootDevice
SystemInfo.BootDevice — Name of the boot device
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str SystemInfo.BootDevice

Description
This variable contains the name of the device that was used to boot REMBO. The
name is one of the following string: "network", "cdrom", "floppy", "initrd" or
"mbr/floppy" (which means either booting from a floppy-disk or from the
hard-disk mbr).

129
VI. Settings built-in variable reference
Table of Contents
Settings.ScreenSaverDelay .................................................................................. 132
Settings.MCASTSpeed ........................................................................................ 133
Settings.MCASTSlowStart.................................................................................. 134
Settings.UseMCAST ............................................................................................ 135
Settings.FASTSpeed............................................................................................. 136
Settings.NetfsLatency .......................................................................................... 138
Settings.ProgressBar............................................................................................ 139
Settings.Compression........................................................................................... 140
Settings.VideoMode ............................................................................................. 141
Settings.AllowScreenShots .................................................................................. 142
Settings.DefaultStyle............................................................................................ 143
Settings.CachePath .............................................................................................. 144
Settings.CachePartMD5 ...................................................................................... 145
Settings.AutoPurge............................................................................................... 146
Settings.AutoBoot................................................................................................. 147
Settings.MaxFileSize............................................................................................ 148
Settings.MaxCallDepth........................................................................................ 149
Settings.SharedPath............................................................................................. 150

Settings contains information that can be changed to modify the behaviour of


REMBO.

130
Settings built-in variable reference
Settings.ScreenSaverDelay
Settings.ScreenSaverDelay — Screen saver activation delay
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
int Settings.ScreenSaverDelay

Default Value
Settings.ScreenSaverDelay = 0;

Description
This variable is used by the REMBO screen saver to determine the time of inactivity
required before starting the screen saver. This time has to be specified in 100th of
second (i.e. a value of 100 corresponds to one second).
See the functions ScreenSaver and ScreenSaverExit in the programmer’s manual
for more information.

132
Settings.MCASTSpeed
Settings.MCASTSpeed — Multicast bandwidth limitation factor
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
int Settings.MCASTSpeed

Default Value
Settings.MCASTSpeed = 0;

Description
This variable is used by REMBO to determine the bandwidth limitation factor for
multicast file downloads. The default value, 0, means no limitation.
A non-zero value is interpreted as a delay to insert every 16 received packets. You
can use the following table to determine which value you need for the bandwidth
utilization you want to achieve:

• Value 0: no bandwidth limitation.


• Value 1: limit bandwidth to 20 Megabits/s.
• Value 2: limit bandwidth to 10 Megabits/s.
• Value 3: limit bandwidth to 5 Megabits/s.
• Value 4: limit bandwidth to 2 Megabits/s.

Higher values will limit the bandwidth even more. Try some of the values to
determine which value fits best with your needs.

133
Settings.MCASTSlowStart
Settings.MCASTSlowStart — Toggle multicast slow start
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
bool Settings.MCASTSlowStart

Default Value
Settings.MCASTSlowStart = false;

Description
This variable is used by REMBO to determine whether or not to start multicast
transfers at full speed. The default is not to slow down transfers, as no strict
synchronization is typically enforced.
In some precises circumstances, it is desirable to start multicast transfers more
smoothly, to allow other clients to join the transfer from the beginning. This is used
in particular by the MetaCast function.

134
Settings.UseMCAST
Settings.UseMCAST — Multicast protocol activation flag
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
bool Settings.UseMCAST

Default Value
Settings.UseMCAST = true;

Description
When this variable is set to true, the MCAST multicast protocol is used for file
downloads when files are accessed through a cache: URL (e.g.
cache://global/test).

In some environments, it might be required to disable multicast when only one


computer is downloading files from the REMBO server to the local cache partition.
Setting the variable Settings.UseMCAST to false will tell REMBO to use the
NETfs (UDP unicast) protocol to transfer files instead of the MCAST protocol.

135
Settings.FASTSpeed
Settings.FASTSpeed — FAST protocol (unicast) bandwidth limitation factor
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
int Settings.FASTSpeed

Default Value
Settings.FASTSpeed = 0;

Description
This variable is used by REMBO to determine the bandwidth limitation factor for
FAST file transfers to the server. The default value, 0, means no limitation (fastest
speed).
A non-zero value is interpreted as a delay to insert every FAST window. A FAST
window is typically 16 kilobytes. You can use the following table to determine
which value to use to limit the bandwidth to a certain amount. You should also
experiment values to determine the exact limitation factor needed in your specific
environment.

• Value 0: no bandwidth limitation.


• Value 1: limit bandwidth to 800 KB/s.
• Value 2: limit bandwidth to 400 KB/s
• Value 3: limit bandwidth to 300 KB/s
• Value 4: limit bandwidth to 200 KB/s

Note that if each computer on the network is connected to a single port on a switch
(full switched network), FAST will have no influence on general network
performance since the switch will not propagate FAST traffic to other nodes (FAST
uses unicast datagrams). You may however notice a slight performance degradation
on other REMBO clients if the REMBO server CPU is saturated by the FAST

136
Settings.FASTSpeed
traffic. You can monitor this specific situation by using the Task Manager under
Windows NT, or top under Solaris/Linux.

137
Settings.NetfsLatency
Settings.NetfsLatency — Network filesystem latency (hundredths)
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
int Settings.NetfsLatency

Default Value
Settings.NetfsLatency = 25;

Description
This variable is interpreted by REMBO as the maximal cache latency for all access
to the network filesystem. The default value, 25, means 250 milliseconds.
This latency parameter has nothing to do with the cache partition or the cache
URLs. It is another way of saving network bandwidth by avoiding to repeat the
same Netfs requests within a short period of time. Repeatitive network requestss
effectively cached by a non-zero netfs latency typically occurs in user scripts and
wizards.
A zero value forces all requests to be transmitted to the server. Larger values
(usually less than 100) allow to avoid unnecessary network trafic.

138
Settings.ProgressBar
Settings.ProgressBar — Progress bar display flag
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
bool Settings.ProgressBar

Default Value
Settings.ProgressBar = true;

Description
If this variable is set to false, no progress bar is shown on the screen during
downloads and disk image restoration.
See also the progress bar functions in the programmer’s manual.

139
Settings.Compression
Settings.Compression — Archive compression factor
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
bool Settings.Compression

Default Value
Settings.Compression = 5;

Description
This variable is the compression level used by Synchronize when creating hard
disk images. Any value between 0 and 9 is valid. A value of 0 means "no
compression", and a value of 9 means "maximum compression".

140
Settings.VideoMode
Settings.VideoMode — Current video mode
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
str Settings.VideoMode

Default Value
Settings.VideoMode = "800x600";

Description
This variable is a Rembo-C enumeration containing the list of all valid graphical
modes. You can change the current video mode by assigning this variable to a new
value (e.g. Settings.VideoMode="1024x768").
To see the list of all valid video modes, use the EnumKeys function:
LogVar(EnumKeys(Settings.VideoMode));.

The value "80x25" means "text mode".

141
Settings.AllowScreenShots
Settings.AllowScreenShots — Toggle activation of the PrintScreen key
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
bool Settings.AllowScreenShots

Default Value
Settings.AllowScreenShots = false;

Description
This variable is off by default, and turned on when loading the administrator plugin
(admin.rbx). When enabled, the REMBO user can use key combinations
Shift-PrintScreen and Alt-PrintScreen to save to a file respectively the content
of the screen and of the current window. The file is named snapshot.bmp, and is
stored in the root directory of the network filesystem, on the server.

142
Settings.DefaultStyle
Settings.DefaultStyle — CSS default style sheet
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
str Settings.DefaultStyle

Description
This variable stores the default CSS (Cascading Style Sheets) stylesheet used by
REMBO when rendering HTML files. You can modify the default stylesheet by
modifying the content of this variable.
The default value of this variable is :
B,STRONG,I,EM,CITE,VAR,TT,CODE,KBD,SAMP,IMG,SPAN
{ display:inline }
LI
{ display:list-item }
PRE,CODE,TEXTAREA
{ white-space:pre }
SELECT,BUTTON
{ white-space:nowrap }

143
Settings.CachePath
Settings.CachePath — Local cache partition path
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
str Settings.CachePath

Default Value
Settings.CachePath = "disk://0:-1";

Description
By default, the local cache partition is the unpartitioned space at the end of the first
hard disk. You can change the location of the local cache partition by modifying this
variable.
For example, to use unpartitioned space on the second disk instead of the first disk
to store the cache, type
Settings.CachePath = "disk://1:-1";

144
Settings.CachePartMD5
Settings.CachePartMD5 — Toggle local cache partition consistency checks
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
bool Settings.CachePartMD5

Default Value
Settings.CachePartMD5 = false;

Description
By default, the local cache partition systematically checks every block read against
a MD5 file downloaded from the server, and validated itself by a global MD5. This
ensures that although the cache partition is stored in an unpartitionned disk space,
its consistency is secured.
In some circumstances, it may be desirable to disable this sanity check. This can be
done using this variable.

145
Settings.AutoPurge
Settings.AutoPurge — Automatically purge oldest cached files
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
bool Settings.AutoPurge

Description
If this variable is set to true, REMBO will automatically purge the oldest files in
the cache partition when there is not enough space to cache a requested server file.
Otherwise, the download of the remote file will fail with an out-of-space eror on
device.
Setting this variable to false may be useful if you have valuable files in your cache
partition, that you do not want to disappear without notice.

146
Settings.AutoBoot
Settings.AutoBoot — Auto reboot on fatal error
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
bool Settings.AutoBoot

Description
If this variable is set to true, the computer is rebooted after 10 seconds if a fatal
error condition occurs. Fatal errors only happens in rare cases when REMBO
cannot handle the error with standard exception handlers.
If this variable is set to false, the computer is not rebooted on fatal errors, but the
error is displayed on the screen and the system is locked.
The initial value of this variable when REMBO starts is determined by the Options
keyword in the server configuration for this host.

147
Settings.MaxFileSize
Settings.MaxFileSize — Maximum Rembo-C recursion level
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
int Settings.MaxFileSize

Default Value
Settings.MaxFileSize = 0x78000000; // ~2GB

Description
This variable sets the maximum file size used by Rembo when generating images. If
an image file is getting larger than this variable, the image is split into several
fragments. The handling of fragments is implicit both at creation and restoration
time.
If you want to create a disk image in fragments that can fit on a CD-ROM, you can
use:
Settings.MaxFileSize = 0x27000000;

148
Settings.MaxCallDepth
Settings.MaxCallDepth — Maximum Rembo-C recursion level
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
str Settings.MaxCallDepth

Default Value
Settings.MaxCallDepth = 1024;

Description
This variable sets the maximum level of recursion allowed in a Rembo-C program.
This is used to prevent programming errors to lock REMBO on an infinite recursion.
Try to run the following Rembo-C code with different values of
Settings.MaxCallDepth and look at the variable level:
int level = 0;
void recurse(void)
{
level++;
recurse(); // recursive call
}

149
Settings.SharedPath
Settings.SharedPath — Shared repository path
Synopsis

Variable information
Read-write, type-protected variable.

Variable declaration
str Settings.SharedPath

Default Value
Settings.SharedPath = "/shared";

Description
This variable defines the location of the shared repository, used to store and retrieve
files associated with disk images (archives).
By default, the shared repository is a relative path. This path is used by
archive-oriented functions and repository functions (see OpenShared or VerifyDla).
It can be also set with a absolute path.
For example, if you want to use an archive stored on your hard-disk, but the shared
repository for this archive is stored on a cdrom, you will have to use an absolute
path:
Settings.SharedPath = "cdrom://0:0/shared";
Synchronize("disk://0:2/myimage","disk://0:1","b");

150
VII. AuthInfo built-in variable reference
Table of Contents
AuthInfo.Success .................................................................................................. 153
AuthInfo.UserName ............................................................................................. 154
AuthInfo.Password............................................................................................... 155
AuthInfo.FullName .............................................................................................. 156

AuthInfo contains information about the authenticated user.

151
AuthInfo built-in variable reference
AuthInfo.Success
AuthInfo.Success — Authentication success flag
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
bool AuthInfo.Success

Default Value
AuthInfo.Success = false;

Description
This variable is set to true if the last authentication attempt with LogonUser, Logon
or AuthUser has succeeded.
Other AuthInfo fields are only valid if AuthInfo.Success is true.

153
AuthInfo.UserName
AuthInfo.UserName — Authenticated user name
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str AuthInfo.UserName

Default Value
AuthInfo.UserName = "";

Description
This variable contains the username of the last authenticated user. The content of
this variable is only valid if AuthInfo.Success is true.

154
AuthInfo.Password
AuthInfo.Password — Authenticated user password
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str AuthInfo.Password

Default Value
AuthInfo.Password = "";

Description
This variable contains the password of the last authenticated user, in clear text. The
content of this variable is only valid if AuthInfo.Success is true.

155
AuthInfo.FullName
AuthInfo.FullName — Authenticated user full name
Synopsis

Variable information
Read-only, type-protected variable.

Variable declaration
str AuthInfo.FullName

Default Value
AuthInfo.FullName = "";

Description
This variable contains the full name of the last authenticated user, if any. If the
authentication server did not provide full name information, this variable is empty.
The content of this variable is only valid if AuthInfo.Success is true.

156
Rembo-C Scripting Reference Manual

157
Rembo-C Scripting Reference Manual
Table of Contents
1. Rembo-C Scripting .............................................................................................. 1
1.1. What are scripts useful for ? ....................................................................... 1
1.2. Embedding scripts in HTML pages ............................................................ 2
1.3. Creating dynamic user interfaces................................................................ 4
1.4. Writing precompiled plug-ins ..................................................................... 5
2. The Language ....................................................................................................... 7
2.1. Structure of a Rembo-C program................................................................ 7
2.2. Variable and Type Declaration.................................................................... 8
2.3. Function Declaration................................................................................. 10
2.4. Expressions ............................................................................................... 11
2.5. Branching Statements ............................................................................... 15
2.6. Working with threads ................................................................................ 16
2.7. Handling exceptions.................................................................................. 17
2.8. Object-Oriented Programming.................................................................. 18
2.9. Pragma Directives ..................................................................................... 19
2.10. Reserved keywords ................................................................................. 19
2.11. Summary of the Differences Between C and Rembo-C ......................... 20
3. Library Functions .............................................................................................. 22
3.1. Library functions by category ................................................................... 22
3.2. String manipulations ................................................................................. 28
Strf............................................................................................................ 28
StrLength.................................................................................................. 31
StrFind ..................................................................................................... 32
StrFindCI ................................................................................................. 34
StrParse .................................................................................................... 35
StrCopy .................................................................................................... 37
StrDelete .................................................................................................. 38
StrInsert.................................................................................................... 39
StrTrim ..................................................................................................... 40
StrCompare .............................................................................................. 41
StrCompareCI .......................................................................................... 42
StrMatch................................................................................................... 43
StrMatchCI............................................................................................... 44
StrChDir................................................................................................... 45
StrGetFileExt ........................................................................................... 46
StrGetFileName ....................................................................................... 47
StrPatch .................................................................................................... 48
StrToUpper............................................................................................... 50
StrToLower .............................................................................................. 51
StrToHTML ............................................................................................. 52
StrFromCP ............................................................................................... 53

i
StrToCP.................................................................................................... 54
StrFromUCS ............................................................................................ 55
StrToUCS ................................................................................................. 56
StrFromUTF8........................................................................................... 57
StrToUTF8 ............................................................................................... 58
SizeToStr.................................................................................................. 59
DateFromInt............................................................................................. 60
3.3. Binary objects manipulations.................................................................... 61
BinCreate ................................................................................................. 61
BinFromHex ............................................................................................ 62
BinToHex ................................................................................................. 63
BinFromStr .............................................................................................. 64
BinToStr ................................................................................................... 65
BinFromInt............................................................................................... 66
BinToInt ................................................................................................... 67
BinGetInt.................................................................................................. 68
BinGetUInt............................................................................................... 69
BinGetStr ................................................................................................. 70
BinGetBin ................................................................................................ 71
BinSetInt .................................................................................................. 72
BinSetStr .................................................................................................. 73
BinSetBin................................................................................................. 74
BinFill ...................................................................................................... 75
BinFind .................................................................................................... 76
BinEFind .................................................................................................. 77
BinReplace............................................................................................... 78
BinSetRandom ......................................................................................... 79
BinGetLine............................................................................................... 80
BinGetNextLinePtr .................................................................................. 81
3.4. Array and structure manipulations............................................................ 82
DeepCopy ................................................................................................ 82
DeepFreeze .............................................................................................. 83
EnumKeys................................................................................................ 84
StructKeys................................................................................................ 85
StructRef .................................................................................................. 86
3.5. Directory manipulations............................................................................ 87
CreateDir.................................................................................................. 87
RenameDir ............................................................................................... 88
RemoveDir ............................................................................................... 89
CopyTree.................................................................................................. 90
MoveTree ................................................................................................. 91
RemoveTree ............................................................................................. 92
ChDir........................................................................................................ 93

ii
LoadDir .................................................................................................... 94
LoadDirMatch.......................................................................................... 96
3.6. File manipulations..................................................................................... 97
CopyFile................................................................................................... 97
PatchFile .................................................................................................. 98
FileDiff..................................................................................................... 99
FilePatch ................................................................................................ 100
RenameFile ............................................................................................ 102
RemoveFile ............................................................................................ 103
FileLink.................................................................................................. 104
SymLink................................................................................................. 106
FileExists ............................................................................................... 107
FileStat ................................................................................................... 108
FileGetAttribute ..................................................................................... 109
FileSetAttribute...................................................................................... 110
3.7. File contents manipulation...................................................................... 111
CreateTextFile........................................................................................ 111
CreateUnicodeFile ................................................................................. 112
CreateMultiUniFile ................................................................................ 113
CreateUTF8File ..................................................................................... 114
CreateHexFile ........................................................................................ 115
CreateBinaryFile .................................................................................... 116
CreateStrFile .......................................................................................... 117
LoadTextFile .......................................................................................... 118
LoadUnicodeFile.................................................................................... 119
LoadMultiUniFile .................................................................................. 120
LoadUTF8File........................................................................................ 121
LoadHexFile .......................................................................................... 122
LoadBinaryFile ...................................................................................... 123
FileOpen................................................................................................. 124
FileRead ................................................................................................. 126
FileWrite ................................................................................................ 127
FileSize .................................................................................................. 128
FileSetSize ............................................................................................. 129
FileTell ................................................................................................... 130
FileSeek.................................................................................................. 131
FileSkip .................................................................................................. 132
FileWriteFrom........................................................................................ 133
FileClose ................................................................................................ 134
3.8. User interface manipulations .................................................................. 135
OpenWindow ......................................................................................... 135
Window .................................................................................................. 136
HideWindow .......................................................................................... 139

iii
ShowWindow ......................................................................................... 140
CloseWindow......................................................................................... 141
ResizeWindow ....................................................................................... 142
AutoResizeWindow ............................................................................... 144
MakeWindow ......................................................................................... 145
ApplyStyle ............................................................................................. 146
Widget.................................................................................................... 147
WidgetNamed ........................................................................................ 149
ScreenShot ............................................................................................. 151
LoadCursor ............................................................................................ 152
ScreenSaver............................................................................................ 153
ScreenSaverExit ..................................................................................... 154
Browse ................................................................................................... 155
Beep ....................................................................................................... 157
3.9. Evaluation-related primitives .................................................................. 158
Exec........................................................................................................ 158
Eval ........................................................................................................ 159
WinEval.................................................................................................. 160
KillThread .............................................................................................. 161
RaiseError .............................................................................................. 162
DefaultExceptionHandler ...................................................................... 166
LogVar.................................................................................................... 168
GlobalVars.............................................................................................. 169
3.10. Persistent Variables ............................................................................... 170
Export..................................................................................................... 170
UnExport................................................................................................ 172
VarToExpr .............................................................................................. 173
3.11. Network-related primitives ................................................................... 174
NetFile.................................................................................................... 174
NetFullPath ............................................................................................ 176
CachedFileStat ....................................................................................... 177
RemoveCachedFile ................................................................................ 178
SysLog ................................................................................................... 179
SysLogF ................................................................................................. 180
DownloadFile......................................................................................... 181
Download ............................................................................................... 182
FileDownloadInProgress........................................................................ 183
MetaCast ................................................................................................ 184
BatchTransfer......................................................................................... 186
CopyCache............................................................................................. 188
GetLock.................................................................................................. 190
ReleaseLock........................................................................................... 192
WakeRemoteHost................................................................................... 194

iv
3.12. System primitives.................................................................................. 195
Interact ................................................................................................... 195
ShowConsole ......................................................................................... 196
HideConsole........................................................................................... 197
Print........................................................................................................ 198
Printf ...................................................................................................... 199
FatalError ............................................................................................... 200
GarbageCollect ...................................................................................... 201
FlushAll ................................................................................................. 202
Keyb ....................................................................................................... 203
CodePage ............................................................................................... 205
Time ....................................................................................................... 208
GetMemoryInfo ..................................................................................... 209
GetNetStats ............................................................................................ 210
GeneratePassword.................................................................................. 212
FileTest................................................................................................... 213
LogDir.................................................................................................... 214
ViewDir.................................................................................................. 215
CMOSRead ............................................................................................ 216
CMOSWrite ........................................................................................... 217
4. Basic Management Operations....................................................................... 218
4.1. Basic management operations by category............................................. 218
4.2. Floppy-disk and ram-disk operations...................................................... 221
BuildFloppyImage ................................................................................. 221
RestoreFloppyImage .............................................................................. 222
CreateRamDisk ...................................................................................... 223
LoadRamDisk ........................................................................................ 224
RDClean................................................................................................. 225
RDLoad.................................................................................................. 226
FreeRamDisk ......................................................................................... 227
CreateRemboFloppy .............................................................................. 228
4.3. Hard-disk setup operations ..................................................................... 230
DeviceCount .......................................................................................... 230
GetPrimaryPartitions.............................................................................. 231
GetPrimaryPartitionsEx ......................................................................... 235
GetLogicalPartitions .............................................................................. 236
GetLogicalPartitionsEx.......................................................................... 237
FindExtendedPartition ........................................................................... 238
ParsePartitions........................................................................................ 239
DescribePartitions .................................................................................. 241
FitPartitions............................................................................................ 242
GetBootablePartition.............................................................................. 243
SetPrimaryPartitions .............................................................................. 244

v
SetPrimaryPartitionsEx.......................................................................... 245
SetLogicalPartitions............................................................................... 246
SetLogicalPartitionsEx .......................................................................... 248
SetBootablePartition .............................................................................. 249
SetOfflineMode...................................................................................... 250
HDClean ................................................................................................ 251
HDCheck................................................................................................ 253
BuildDiskImage ..................................................................................... 254
RestoreDiskImage.................................................................................. 255
CreateRemboCDRom ............................................................................ 257
4.4. Protected partitions handling .................................................................. 258
ClearProtectedPartitions ........................................................................ 258
GetProtectedPartitions ........................................................................... 259
SetProtectedPartitions ............................................................................ 261
GetBEER................................................................................................ 264
SetBEER ................................................................................................ 265
GetBEEREntry....................................................................................... 266
SetBEEREntry ....................................................................................... 267
HideProtectedPartitions ......................................................................... 269
UnhideProtectedPartitions ..................................................................... 271
WriteRemboProtectedMBR................................................................... 273
4.5. Booting functions.................................................................................... 275
HDBoot .................................................................................................. 275
RDBoot .................................................................................................. 276
LXBoot .................................................................................................. 277
FloppyBoot ............................................................................................ 279
Reboot .................................................................................................... 280
PowerOff ................................................................................................ 281
BIOSBoot............................................................................................... 282
4.6. GUI functions.......................................................................................... 283
MessageBox........................................................................................... 283
Logon ..................................................................................................... 284
FileChooser ............................................................................................ 285
OpenProgressBar ................................................................................... 286
SetProgressBar....................................................................................... 288
SetProgressInfo ...................................................................................... 289
CloseProgressBar................................................................................... 290
OpenMessage......................................................................................... 291
OpenNotice ............................................................................................ 292
OpenYesNo ............................................................................................ 294
OpenMenu.............................................................................................. 296
OpenEval................................................................................................ 298
BuildFileSelect....................................................................................... 300

vi
4.7. Applicative functions .............................................................................. 302
FDisk...................................................................................................... 302
FileMan .................................................................................................. 303
TextEdit.................................................................................................. 304
OpenHTML............................................................................................ 305
4.8. User console control ............................................................................... 307
AddToRootMenu ................................................................................... 307
LockKeyboard........................................................................................ 308
LockMouse ............................................................................................ 309
LockScreen ............................................................................................ 310
AddRemoteConsole ............................................................................... 311
KillRemoteConsole................................................................................ 312
5. Advanced Management Operations............................................................... 313
5.1. Advanced management operations by category...................................... 313
5.2. Virtual and Loopback Images functions ................................................. 320
CreateVirtualImage ................................................................................ 320
LinkTree................................................................................................. 322
UnlinkTree ............................................................................................. 323
FreeVirtualImage ................................................................................... 324
CreateLoopback ..................................................................................... 325
CloseLoopback ...................................................................................... 326
5.3. Advanced imaging functions .................................................................. 327
OpenArchive .......................................................................................... 327
CloseArchive.......................................................................................... 328
OpenDiff ................................................................................................ 329
CloseDiff................................................................................................ 330
ArchiveType........................................................................................... 331
OpenArchDevice.................................................................................... 332
CloseArchDevice ................................................................................... 333
Synchronize............................................................................................ 334
SynchronizeEx ....................................................................................... 338
TextDiff .................................................................................................. 339
MakeDiffFromText ................................................................................ 340
ApplyDiff ............................................................................................... 341
5.4. Shared files repository manipulation functions....................................... 342
OpenShared............................................................................................ 342
MarkShared............................................................................................ 344
StatShared .............................................................................................. 346
SweepShared.......................................................................................... 349
CompactShared ...................................................................................... 351
CloseShared ........................................................................................... 353
VerifyDLA ............................................................................................. 354
GetSharedSize........................................................................................ 356

vii
5.5. Windows NT registry operations ............................................................ 357
OpenRegistry ......................................................................................... 357
CloseRegistry......................................................................................... 358
NTSetPartition ....................................................................................... 359
NTDetect................................................................................................ 360
NTCleanSignature.................................................................................. 361
Win2KRegisterHDD .............................................................................. 362
NTMapDrives ........................................................................................ 363
Win2KRegisterParts............................................................................... 364
Win2KChangeIPInfo ............................................................................. 365
Win2KChangeNameServers .................................................................. 366
NTSetBootTimeout................................................................................ 367
NTSetNetbiosName ............................................................................... 368
NTSetHostName .................................................................................... 369
NTSetWinlogonDomain ........................................................................ 370
NTChangeName .................................................................................... 371
NTInstallService .................................................................................... 372
NTAutoLogon ........................................................................................ 373
NTJoinDomain....................................................................................... 374
NTForcePwdChange.............................................................................. 376
GetSIDFromFile .................................................................................... 377
GetSIDFromRegistry ............................................................................. 378
ApplySID ............................................................................................... 379
GenerateSID........................................................................................... 381
SIDToStr ................................................................................................ 383
PatchSIDReg.......................................................................................... 384
PatchSID ................................................................................................ 385
5.6. INI file operations ................................................................................... 387
NewIniFile ............................................................................................. 387
ParseIniFile ............................................................................................ 388
ParseIniFileDef ...................................................................................... 389
ParseIniString......................................................................................... 390
BuildIniFile ............................................................................................ 391
BuildUnquotedIniFile ............................................................................ 392
TestIniValue ........................................................................................... 393
GetIniValue ............................................................................................ 394
GetIniStruct............................................................................................ 395
SetIniValue............................................................................................. 396
SetIniStruct ............................................................................................ 397
AddIniValue ........................................................................................... 398
AddIniSection ........................................................................................ 399
DiffIniFile .............................................................................................. 400
PatchIniFile ............................................................................................ 401

viii
5.7. Hardware and network detection ............................................................ 402
GetPnPCards .......................................................................................... 402
GetSystemDevices ................................................................................. 403
GetPCICards .......................................................................................... 404
PCIFindDevice....................................................................................... 405
PCIGetBusCount ................................................................................... 406
PCIGetSlot ............................................................................................. 407
PCIReadByte.......................................................................................... 408
PCIReadWord ........................................................................................ 409
PCIReadDWord...................................................................................... 410
PCIWriteByte......................................................................................... 411
PCIWriteWord ....................................................................................... 412
PCIWriteDWord..................................................................................... 413
PortOutByte ........................................................................................... 414
PortOutWord .......................................................................................... 415
PortInByte .............................................................................................. 416
PortInWord............................................................................................. 417
HWSignature.......................................................................................... 418
GetDMITables........................................................................................ 419
GetDMIStrings....................................................................................... 420
DMIProcessorInfo.................................................................................. 421
DMISystemInfo ..................................................................................... 422
DMIMemoryInfo ................................................................................... 423
DMIBIOSInfo ........................................................................................ 424
DMIOnBoardDev .................................................................................. 425
GetExtDiskInfo ...................................................................................... 426
IDEDetect .............................................................................................. 427
Win2KRegisterBootDevice.................................................................... 429
GetNICType ........................................................................................... 430
GetNICs ................................................................................................. 431
ProbeServer............................................................................................ 433
RequestDHCPInfo ................................................................................. 434
ReleaseDHCP ........................................................................................ 435
LoadUNDI ............................................................................................. 436
SetIPInfo ................................................................................................ 437
GetNetPass............................................................................................. 438
GetServerInfo......................................................................................... 439
5.8. Crypto and authentication functions ....................................................... 440
MD5Create............................................................................................. 440
MD5Update............................................................................................ 441
MD5Finish ............................................................................................. 442
BlowFishEncrypt ................................................................................... 443
BlowFishDecrypt ................................................................................... 444

ix
AuthUser ................................................................................................ 445
AuthUserEx............................................................................................ 447
5.9. TCP connectivity functions..................................................................... 449
TCPConnect........................................................................................... 449
TCPRead ................................................................................................ 451
TCPWrite ............................................................................................... 453
TCPClose ............................................................................................... 455
SendMail ................................................................................................ 457
SQLOpen ............................................................................................... 459
SQLOpenEx........................................................................................... 461
SQLQuery .............................................................................................. 464
SQLClose............................................................................................... 466
SQLQuickQuery .................................................................................... 467
5.10. Other system primitives ........................................................................ 468
DeviceBlank........................................................................................... 468
DeviceClean ........................................................................................... 469
DeviceCleanEx ...................................................................................... 470
DeviceGetInfo........................................................................................ 471
DeviceCleanForce.................................................................................. 472
DevicePreAdapt ..................................................................................... 473
DeviceAdapt .......................................................................................... 474
DeviceClose ........................................................................................... 475
DeviceCheck .......................................................................................... 476
DeviceSetDirty....................................................................................... 478
DeviceBoot ............................................................................................ 479
FileBoot ................................................................................................. 480
DeviceInfo.............................................................................................. 481
DeviceAllocInfo..................................................................................... 483
DeviceGetFsType................................................................................... 484
WriteOfflineCode................................................................................... 485
DevReadBootSects ................................................................................ 486
DevWriteBootSects................................................................................ 487
DevReadLabel........................................................................................ 488
DevWriteLabel....................................................................................... 489
DevReadUUID....................................................................................... 490
DevWriteUUID...................................................................................... 491
InitDownload ......................................................................................... 492
InitUDownload ...................................................................................... 493
MoreDownload ...................................................................................... 494
InfoDownload ........................................................................................ 495
DownloadResult..................................................................................... 496
InitBatchTransfer ................................................................................... 497
AddToBatchTransfer.............................................................................. 499

x
MoreBatchTransfer ................................................................................ 500
InfoBatchTransfer .................................................................................. 501
InitSynchro............................................................................................. 502
MoreSynchro.......................................................................................... 503
InfoSynchro............................................................................................ 504
SynchroStats .......................................................................................... 505
ApplyTextDiff ........................................................................................ 506
InitRemboFloppy ................................................................................... 508
InitRemboCDRom ................................................................................. 510
MoreRemboClone.................................................................................. 512
BuildFileIndex ....................................................................................... 513
GUnzip................................................................................................... 514
Rembo-C functions index .................................................................................... 515

xi
List of Tables
1-1. Encoding of the KeyControl byte ....................................................................... 3
1-2. Encoding of the MouseButtons byte .................................................................. 3
2-1. Operator Precedence In Rembo-C.................................................................... 12
2-2. Rembo-C reserved keywords............................................................................ 19
3-1. String manipulations......................................................................................... 22
3-2. Binary objects manipulations ........................................................................... 23
3-3. Array and structure manipulations ................................................................... 24
3-4. Directory manipulations ................................................................................... 24
3-5. File manipulations ............................................................................................ 24
3-6. File contents manipulation................................................................................ 25
3-7. User interface manipulations ............................................................................ 26
3-8. Evaluation-related primitives............................................................................ 26
3-9. Persistent Variables........................................................................................... 27
3-10. Network-related primitives ............................................................................. 27
3-11. System primitives ........................................................................................... 27
4-1. FDTitle;........................................................................................................... 218
4-2. Hard-disk setup operations ............................................................................. 218
4-3. Protected partitions handling .......................................................................... 219
4-4. Booting functions ........................................................................................... 219
4-5. GUI functions ................................................................................................. 220
4-6. Applicative functions...................................................................................... 220
4-7. User console control ....................................................................................... 220
4-1. MessageBox buttons codes............................................................................. 283
5-1. Virtual and Loopback Images functions......................................................... 313
5-2. Advanced imaging functions .......................................................................... 313
5-3. Shared files repository manipulation functions .............................................. 313
5-4. Windows NT registry operations .................................................................... 314
5-5. INI file operations........................................................................................... 315
5-6. Hardware and network detection .................................................................... 316
5-7. Crypto and authentication functions............................................................... 317
5-8. TCP connectivity functions ............................................................................ 317
5-9. Other system primitives.................................................................................. 318
List of Figures
4-1. Logon dialog box............................................................................................ 284
4-1. FileChooser dialog.......................................................................................... 285
4-1. Progress bar window ...................................................................................... 287
4-1. Sample OpenMessage window....................................................................... 291
4-1. Sample OpenNotice window .......................................................................... 293
4-1. Sample OpenYesNo window .......................................................................... 295
4-1. Sample OpenMenu window ........................................................................... 297

i
4-1. Sample OpenEval window ............................................................................. 299
4-1. FDisk tool ....................................................................................................... 302
4-1. FileMan Application....................................................................................... 303
4-1. TextEdit tool ................................................................................................... 304
4-1. OpenHTML on this page................................................................................ 305

ii
Chapter 1. Rembo-C Scripting

This chapter explains the purpose and the use of Rembo-C scripts and plug-ins.
Some general how-to advices are also given. The details of the programming
language are described in the forthcoming chapters.

1.1. What are scripts useful for ?


Scripts are useful to automate your management operations, and to handle special
operations that are not covered by the standard wizards distributed with REMBO.
You can perform a number of tasks by just a few clicks using REMBO wizards.
REMBO Professional and REMBO Enterprise even include wizards to setup
automatic operating system restauration and boot menus. However, if you cannot
use them for your purpose, you will need scripting to design your own automated
procedures. Scripts are also very convenient if you often have to build disk images
and do not want to have to do it interactively.
When a REMBO client computer is started, it starts by loading its startup page (as
defined in the server configuration, by default rembo.shtml). The body of the page
is displayed on the desktop, and if there is a <SCRIPT> section in the page, it is
compiled and executed. This is the place to put your custom automation code.

It is recommended not to edit the file rembo.shtml directly, as this file is part of
REMBO distribution and is likely to be overwritten when you upgrade REMBO.
Instead of this, change the startup page for your hosts (or group of hosts) to
another name, and use this name to create your custom startup page.

Scripts can contain statements, that are executed immediately, or function


definitions, to be executed later when the function is invoked. Functions can be used
as shortcut for commonly used sequences of operations. Once a function is defined,
it can be called from any script, from the interactive evaluator and from HTML
callbacks. The use of HTML callbacks is described in Section 1.2;
If you want to split your Rembo-C scripts into several files, you can use the Exec
function to launch a new execution thread on another Rembo-C file. Note that the
target file is not expected to be an HTML file, and therefore the code should not be
enclosed within <SCRIPT> tags. If you want to load and execute all statements and
definitions of a child Rembo-C file before continuing the evaluation of the parent
file (the usual semantic for include files), you will typically use the following
syntax:
join(Exec("includefile.rbc"));

1
Chapter 1. Rembo-C Scripting

1.2. Embedding scripts in HTML pages


Scripts are typically used as the active content of an HTML page (whereas the
HTML text define the visual aspect of the page). There are two places where you
can put Rembo-C scripts in an HTML page:

1. between <SCRIPT> tags in the header of the page


2. in the event handlers callbacks

In order to be executed by REMBO, a script embedded in an HTML page must be


declared of type text/rembo-c. Otherwise, it will be simply discarded. The simple
example below is a valid HTML page with a Rembo-C script correctly embedded.
<!-- Sample HTML page illustrating the use of Rembo-C scripts -->
<title>Sample page</title>
<script type="text/rembo-c">
int i;
for(i = 0; i < 5; i++)
Print("Hello world !");
</script>
<body>
This sample page contains a Rembo-C script that
has written a message five times in the console log.
</body>

Event handler callbacks are small fragments of Rembo-C code that are executed
when a specific event occurs, usually caused by user interaction. Event handlers are
normally bound to widgets (buttons, input area, ...) but they can be used with almost
any HTML tag. You can define an event handler using the on... HTML attributes:

• onmousedown: this event is triggered when the user press the mouse button on
the target;
• onmouseup: this event is triggered when the user releases the mouse button on
the target;
• onclick: this event is triggered when the user releases the mouse button on the
target shortly after having pressed on it;
• ondblclick: this event is triggered when the user clicks twice within a short period
of time;

2
Chapter 1. Rembo-C Scripting
• onmouseover: this event is triggered when the mouse enters the area covered by
the target;
• onmousemove: this event is triggered when the mouse move within the area
covered by the target;
• onmouseout: this event is triggered when the mouse leaves the area covered by
the target;
• onkeypress: this event is triggered when a key has been pressed, or when has been
kept pressed for some time (auto-repeat)
• onkeydown: this event is triggered when a key is pressed
• onkeyup: this event is triggered when a key is released
• onsubmit: this event is triggered when the enter key is pressed in an input field, or
when a submit button is clicked.
• onfocus: this event is triggered when the target receives the focus
• onblur: this event is triggered when the target looses the focus
• onchange this event is triggered when the target looses the focus and its value has
been edited by the user

Before evaluating the Rembo-C expression in an event handler callback, all


occurences of the identifier Keypressed are substituted by the character string
representing the last key pressed, all occurences of the identifier KeyControl are
substituded by a numeric value encoding the state of the keyboard control keys and
all occurences of the identifier MouseButtons are substituded by a numeric value
encoding the state of the mouse buttons. The following values are OR-ed to make
the keyboard control status:
Table 1-1. Encoding of the KeyControl byte

Scroll-Lock 1
Num-Lock 2
Caps-Lock 4
Pause 8
Alt 32
Ctrl 64
Shift 128

The following values are OR-ed to make the mouse buttons status:
Table 1-2. Encoding of the MouseButtons byte

3
Chapter 1. Rembo-C Scripting

Left button 1
Right button 2
Center button 4

The following example illustrate the use of event handler callbacks.


<!-- Sample HTML page illustrating the use of event handlers -->
<title>Event Handler example</title>
<script type="text/rembo-c">
void KeyHandler(str theKey)
{
Print("User has pressed the "+theKey+" key<br>");
}

void ClickHandler(void)
{
Print("Click !<br>");
}
</script>
<body>
Sample input: <input onkeypress="KeyHandler(Keypressed);"><br>
Sample button: <button onclick="ClickHandler();">click me</button><br>
Active <it onclick="ClickHandler();">text</it><br>
</body>

1.3. Creating dynamic user interfaces


Most modern user interfaces dynamically change aspect as the user interact with
them: buttons get enabled and disabled, text fields receive default values depending
on the result of a computation involving other fields, panels display informations
specific to a selected item.
Although REMBO user interface is HTML based, such dynamic behaviour can
easily be achieved using Rembo-C scripts. This is done by changing the content of a
page or widget from within a script or a callback.
From a programming point of view, an HTML page is a hierarchy of nested
widgets: a border widget (providing a title and outside borders), a frame widget
(providing inside borders and scroll bars), a flowed widget (providing flowed
content) and many possible enclosed subwidgets, possibly further nested.
There are two ways you can dynamically change the appearance and content of a
widget: using the display filesystem, which maps the widget hierarchy to a file tree,
or using the corresponding pseudo-variables. Both are roughly equivalent, and each
might be more convenient to use in some precise circumstances.

4
Chapter 1. Rembo-C Scripting
When accessing a widget through the display filesystem, each directory corresponds
to a widget. Two special files are present in every directory: SELF and SELF-APPEND.
When SELF is rewritten, the widget is destroyed and rebuild from the HTML text
written to the file. When SELF-APPEND is rewritten, the widget will try to append the
HTML code written to the file to its own definition (not all widgets support this).
Reading SELF may provide some informations on the content of the widget, but is
not guaranteed to return HTML code representing the full current state of the
widget.
Accessing widgets through variable is mostly convenient in event handlers, as any
event handler thread is bound to the window which triggered the event and can
therefore access its named widgets directly, as any global variable:
<title>Dynamic HTML example</title>
<script type="text/rembo-c">
void KeyHandler(void)
{
InputData.value = StrToUpper(InputData.value);
}
</script>
<body>
Type your text, I will capitalize it:
<input name=InputData onkeyup="KeyHandler();">
</body>

For more details about the use of widgets pseudo-variables, see the manual pages
for Window, Widget and WidgetNamed. For more advanced examples of dynamic
interfaces, have a look at the source code of the wizards, which is distributed as part
of the software development kit.

1.4. Writing precompiled plug-ins


As you get experienced with Rembo-C programming, you may want to develop
your own reusable libraries of functions. A set of functions that are grouped
together to provide a given new functionality in REMBO is called a Plug-in. You
can distribute Plug-ins as stand-alone extension modules for REMBO
Whether for performance reasons or to protect your intellectual property rights, you
may not want to distribute the source code of your plug-ins. In this case, you should
precompile your .rbc file into a .rbx file, and distribute the .rbx file only. This
precompilation can be done using rbcc, the Rembo-C compiler (available in the
optional software development kit for REMBO Professional, and included in
REMBO Enterprise).
Here is the description of the arguments to the command line Rembo-C compiler.

rbcc [-g] [-h] [-o outputfile] sourcefile

5
Chapter 1. Rembo-C Scripting

• -g: include source-level debug informations in the compiled file, so that the
description of error messages includes the exact location of the error;
• -h: outputs the result as a comma-separated list of ascii-encoded bytes, for
instance for inclusion in the source code of a packaging program;
• -o : specify the name of the output file. Defaults to the same name as the source,
but with a .rbx extension for regular compiled files or .rbh extension for
ascii-encoded compiled files.

Users of REMBO Classic can only execute Rembo-C precompiled plug-ins


coming from Rembo Technology SaRL. If you want to distribute a plug-in to a
REMBO Classic user, you have to send him the source code.

6
Chapter 2. The Language

This chapter explains the syntax of Rembo-C, a far descendant of C with a flavor of
Java. In brief, the additions to C are:

• separate boolean type


• easy string manipulations
• auto-growing arrays
• implicit dynamic memory allocation with garbage collection
• polymorphic (weak-typed) objects
• declaration of variables as a regular statement
• dynamic case switching
• dynamic linking through inter-module global variables
• nested functions
• automatic array bound checking

The features not available in Rembo-C are:

• macro preprocessing
• pointer arithmetic
• floating point numbers
• lazy evaluation of boolean expressions
• unions
• strong typing for structured types
• prototyping for user-defined functions

For a more systematic review of differences between C and Rembo-C, see Section
2.11.

7
Chapter 2. The Language
2.1. Structure of a Rembo-C program
The syntax of Rembo-C is very similar to that of C. All identifiers are
case-sensitive. A Rembo-C program is a collection of statements, which might be:

• A compound statement (i.e., statements included between braces)


• The declaration of a variable or structured type
• The declaration of a function
• An expression (including a function call)
• A branching statement (if, while, do, for, switch, goto, return)
• A pragma directive

Comments can be inserted in the source code using either the traditional C
bracketing (i.e., /* ... */) or using C++/Java style (i.e., // followed by a comment
until the end of the line).

2.2. Variable and Type Declaration


Variable declaration can happen at any place where a statement is allowed
(including in the first part of a ’for’ statement). Variable declared at the top-level are
visible to all modules running in a Rembo environment.
Rembo-C only uses four basic types:

• int for numbers (32-bits signed integers)


• bool for booleans (can take the value ’true’ or ’false’)
• str for strings (null-terminated, unlimited strings)
• var for references to any object (including those above plus arrays, structures,
enumerations, functions...)

Variables are declared similarly to C, with a possible initialization expression. The


const keyword can be used to mark a variable read-only. If you want to make a
variable visible only for current module, you can declare it locally within a
compound statement. Therefore, there is no need for a static modifier.
Examples:
int x, y;
str target = "world";
str greetings = "Hello "+target;
var v = target;

8
Chapter 2. The Language
const bool DEBUG = true;

Arrays are defined as in C. If no size is specified at the time of declaration, the array
is assumed to be auto-growing (elements will be automatically allocated the first
time they are referenced). Array initializer can be any valid sequence of
expressions, enclosed between curly braces. If the initializer is shorter that the size
of the array, the remaining elements will be set to zero.
Examples:
int values[100];
str textbuffer[];
int coord[4] = { x, y, z };

As in C, multidimensional arrays cannot be declared directly. Instead, use an array


of var and initialize it with the desired array elements.
Two kinds of user-defined types are available: enumerated types and structures. As
in C, a user-defined type can be either

• bound to an identifier for later use


• used immediately to declare one or more variable
• both together
In other words, the valid syntax is

enum [enum-name] {
enum-keys
} [var-list];
struct [struct-name] {
fields-decl
} [var-list];

Unlike C, enumerated variables are not identical to numbers. They can be used
wherever a numeric variable is required, but they can also be used wherever a string
variable is required. In the latter case, the string representation of the key is used.
As arrays, structure variable can be initialized using a braced list of expressions.
Structures can be freely nested.
Examples:
enum Color {
white, black, red, green, blue, yellow

9
Chapter 2. The Language
};
enum Color bgcol, fgcol = 1;
enum { yes, no } answer = "yes";
struct Point {
int x,y;
};
struct Line {
struct Point start;
struct Point stop;
};
struct Point pt = { 10, 15 };
struct Line l1, l2 = { pt, { 20, 25 }};

2.3. Function Declaration


Function are defined as in C. In the declaration header of a function, only the four
basic types (int, bool, str, var) and coid can be used. However, var arguments and
return values can be used to return any type of object, including arrays, structures
and even functions.
Arguments of type int, bool and str are passed by value; var arguments are passed
by reference.
There is no need to prototype functions, and there is no compile-time type checking
for the arguments of user-defined function. Argument and return value types are
anyway checked at run time.
Unlike in C, a Rembo-C function can freely return an automatically allocated
variable (such as a local variable of type array), because Rembo-C includes an
automatic garbage collector that will recover the storage at the time it is not
anymore used.
Example:
int fact(int n)
{
if(n > 1)
return n * fact(n-1);
else
return 1;
}

If you want to make a function visible only for current module, you can declare it
locally within a compound statement. Therefore, there is no need for a static
modifier.
Example:

10
Chapter 2. The Language
var fibo; // this variable is global

/*
* Start a compound statement to define local stuff
*/
{
/*
* This is a local function
*/
int fibobody(int n, int sum, int prev)
{
if(n > 0)
return fibobody(n-1, sum + prev, sum)
else
return sum;
}

/*
* This is also a local function for now
*/
int fibomain(int n)
{
if(n > 1)
return fibobody(n-1, 1, 0);
else
return n;
}

fibo = fibomain; // publicize the function !


}

See also the section on object-oriented programming.

2.4. Expressions
As for variables, there are four types of expressions:

• numeric expressions
• boolean expressions
• string expressions
• variable expressions

Strong type-checking is performed on the parts of expressions involving numeric,


boolean and string expressions. Variable expressions are resolved at runtime,
allowing for some forms of polymorphism. The Rembo-C compiler performs a

11
Chapter 2. The Language
simple type-inference to determine the type of unknown (global) variables in
expressions, on the basis of the operator used.
The expression syntax mainly follow that of C. The recognized operators are listed
below, sorted by priority (lines in the same paragraph have the same priority, and
are processed according to the given associativity).
Table 2-1. Operator Precedence In Rembo-C

operator meaning associativity


var(...) function/primitive call -->
var.name struct reference
var[int] array reference
var[int] character reference
sizeof(str) string length
typeof(any) object type id

~int bitwise compliment <--


+int unary plus (no effect)
-int unary minus (opposite)
!bool logical negation
var++ post-increment
var-- post-decrement
++var pre-increment
--var pre-decrement

int * int multiplication -->


int / int division
int % int remainder

int + int addition -->


int - int substraction
str + str concatenation

int >> int bitshift right -->


int << int bitshift left

int & int bitwise and -->

int ^ int bitwise xor -->

12
Chapter 2. The Language

operator meaning associativity


int | int bitwise or -->

int < int numeric ordering -->


int <= int
int >= int
int > int
str < str string ordering
(ASCII-based)
str <= str
str >= str
str > str

int == int numeric comparison -->


int != int
bool == bool boolean comparison
bool != bool
str == str string comparison
str != str

bool && bool boolean and -->

bool || bool boolean or -->

bool ? int : int conditional expression <--


bool ? bool : bool
bool ? str : str
bool ? var : var

var = int numeric assignment <--


var += int addition and assignment
var -= int substraction and
assignment
var *= int multiplication and
assignment
var /= int division and assignment
var %= int remainder and assignment
var &= int bitwise-and and
assignment

13
Chapter 2. The Language

operator meaning associativity


var ^= int bitwise-xor and
assignment
var |= int bitwise-or and assignment
var <<= int left bitshift and
assignment
var >>= int right bitshift and
assignment
var &&= bool boolean-and and
assignment
var ||= bool boolean-or and
assignment
var = var copy assignment
var := var reference assignment
var <=> var variable hot-swap

expr, expr sequence operator -->


Note that in addition to typing separately boolean and integers, Rembo-C also gives
a higher priority to bitwise operators than to comparison operators.
Unfortunately, Rembo-C does not provide lazy evaluation. That means, a boolean
expression is evaluated completely even if the first part of the expression entirely
determines the result. The same remark applies for conditional expressions: both
members of the alternative are evaluated before one of them is discarded.
Rembo-C provides two construction for building online arrays within an expression

• For building an uninitialized array, simply use a basic type name followed by the
(optional) size between square brackets
• For building an initialized array, enclose the items between curly braces, and
separate them with commas. Any expression can be used within an inline array
construction.

Examples:
PrintArray( { 1,2,3,i,j } ); // assume i and j are variables
var arr1 = int[10]; // fixed-size array
var arr2 = int[]; // auto-resizable array

14
Chapter 2. The Language
Array range checking is performed automatically. In the case of auto-resizable
array, an index greater than the size of the array does not rise an error but cause the
array to grow to the minimal size necessary for the requested element to exist.
As for arrays, strings can be indexed to retrieve individual characters. As for arrays,
a string not marked as ’const’ automatically grows when the index of the referred
character is larger than the size of the string. Intermediate positions are filled with
spaces.
For convenience puposes, single-character strings extracted by indexing a string can
be used as a numeric variable, corresponding to the ASCII code of the character.

2.5. Branching Statements


The branching statements are the same as in C:

• if(...) ... [else ...]


• while(...) ...
• do ... while(...);
• for(... ; ... ; ...) ...
• switch(...) { case ...: ... [default: ...] }
• break;
• continue;
• goto ...;
• return [...];

The branching conditions for ’if’ and ’while’ must be of type bool. As an addition
to C, ’case’ expressions do not need to be constants, but can be any expression of a
type compatible with the ’switch’ expression.
Examples:
if(y > x) // if(...) ... else ...
diff = y - x;
else
diff = x - y;

if(point.x==x && point.y==y) // if(...) ...


hit = true;

while(x-- > 0) { // while(...) ...


Print(x);
y += x;

15
Chapter 2. The Language
}

do { // do ... while(...)
s += "*-";
} while(sizeof(s) < 80);

for(int i = 0; i < 10; i++) // for(...; ...; ...) ...


Print(i, "; ");

switch(st) { // switch(...) { ... }


case "bip":
st[2] = "o";
break;
case "bop":
st[2] = "a";
break;
case (str)i:
st = (str)i;
default:
Print("error !");
}

allover: // (see ’goto’ later on)

switch(true) { // switch(...) { ... }


case x == 0:
z = 5 - x;
break;
case x > 5:
goto allover; // goto ...
default:
z = x * x;
}

2.6. Working with threads


The REMBO virtual machine is multi-threaded. That means, several execution
threads can run simultaneously in the virtual machine, and each one receives a part
of the CPU time. Multitasking is real-time preemptive (i.e., each thread is allocate a
precise time slice), but primitives are atomic and therefore sometime overrun their
time slice.
A new thread is created for each user interaction (HTML event handler), when an
exception is raised and for each Eval or Exec invocation. These two primitives
return a thread identifier, that can be used later on to interact with the thread. The
identifier of the running thread can be retrieved using the keyword SELF.

16
Chapter 2. The Language
You can wait for a thread to terminate using the join(threadid) special form. This
is specially usefull in conjunction with Eval and Exec if you want to ensure that the
evaluation is completed before resuming the calling thread. When a thread waits for
another thread to terminate, it yields to the running threads without waiting for its
time slice to be elapsed. This is why join is a special form and not a regular
primitives.
You can pause the execution of a thread for a given period (specified in hundredths
of a second) using the delay(num) special form. When a thread is paused, it yields
to the running threads without waiting for its time slice to be elapsed. This is why
delay is a special form and not a regular primitives.

You can kill any thread using KillThread.


There is currently no mechanism in Rembo-C to prevent two threads from accessing
concurrently a variable, although this is likely to be introduced in future releases.
This should not be a major problem, as VM opcodes and primitives are atomic. If
you want to avoid the two threads execute the same function concurrently, you
should use a global variable as a pseudo-mutex (although it is not 100% safe).

2.7. Handling exceptions


When an error occurs in a Rembo-C program, the virtual machine raises an
exception. The thread at the origin of the exception is temporarily suspended, and a
new prioritary thread is created to execute the exception handler.
Rembo-C allows the definition of (possibly nested) local exception handler using
the with...try statements:
// Define our exception handler
var myExceptionHandler(var exc)
{
SysLog("Resumable error: "+exc.msg);
exc.resume = true;
return exc;
}

with(myExceptionHandler) try {
// this will raise an exception (no such device)
FileLoad("blurp://nofile");
// code here will never be executed
Print("never reached\n");
}
// Execution will resume here
Print("execution resumed\n");

17
Chapter 2. The Language
As shown in the example above, in addition to storing or signaling the exception,
the exception handler can decide what to do next with the exception. The following
actions are possible:

• forwarding the exception to the next exception handler (the default);


• resuming the faulty thread at the end of the try block, as shown in the example
above;
• killing the faulty thread using the KillThread primitive, and cancelling the
propagation of the exception.

When no local exception handler is defined, or if all local exception handlers have
forwarded the exception, the predefined function ExceptionHandler is invoked to
handle the exception. By default, this function kills the faulty thread, displays the
error message in red on the console, and send it to the server using SysLog.
Exception handlers receive as argument a structure describing the exception that
was raised. The detail of this structure is defined in the manual page of
DefaultExceptionHandler.

If an exception is raised within an exception handler, a simpler built-in exception


handler that kills both faulty threads is invoked.
You can force an exception to be raised using the RaiseError function.

2.8. Object-Oriented Programming


Althought Rembo-C is not an object-oriented programming language, it is very easy
to use it for object-oriented programming. This is made possible by the dynamic
variable allocation scheme used by Rembo-C, inspired by the family of functional
languages (LISP, ...). Look closely at the following example:
var NewCounter(void)
{
// attributes
int val;

// methods
void inc(void) { val++; }
void dec(void) { val--; }
int value(void) { return val; }

// public definition
struct {
var Inc = inc;
var Dec = dec;
var Value = value;
} self;

18
Chapter 2. The Language

return self;
}

When NewCounter is called, the Rembo-C interpreter allocates storage for the
variable var, as well as for each of the functions defined within NewCounter. These
functions are dynamically linked to the newly allocated variable var. All three are
then returned as members of a structure. This make possible the following calling
sequence:
var count = NewCounter(); // instanciate a new counter

count.Inc(); // increment it
Print(count.Value()); // print its value

which looks pretty much like object-oriented programming.

2.9. Pragma Directives


The Rembo-C compiler currently supports three directives:

• #pragma purge <global-variable-name>: Undefine a global variable.


• #pragma clear <global-variable-name>: Reset the content of a global variable
to NIL. This is usefull for instance to reassign the content of a type-protected
variable.
• #pragma protect <var-variable>: Protect the given var variable from having its
type changed by the =, := or the <=> operators.

2.10. Reserved keywords


The following table list the reserved keywords of Rembo-C. Keywords cannot be
redefined or be used as identifier.
Table 2-2. Rembo-C reserved keywords

int bool str var const see


Section
2.2
void enum struct see
Section
2.2

19
Chapter 2. The Language

NIL sizeof typeof see


Section
2.4
if else switch break case default see
Section
2.5
for while do continue goto return see
Section
2.5
join delay SELF see
Section
2.6
with try see
Section
2.7
pragma purge clear protect debug see
Section
2.9

2.11. Summary of the Differences Between C and Rembo-C

• Syntax:

• Character constants do not exist, using single-char strings instead


• Function definitions can be nested
• Out-of-function statements are allowed
• Variable declaration are allowed at any place where a statement is allowed
• There is no ’static’ modifier, but local variables can do the same job

• Operators:

• The operators +, <, <=, >=, >, ==, != can be used on strings
• Bitwise operators have a higher priority than logical operators
• Boolean and conditional operators do not perform lazy evaluation
• There are a two additional operators := and <=> for manipulating variables
• Operator [] provides for automatic range-checking

20
Chapter 2. The Language
• Operator sizeof answers the number of elements in an array/structure, the size
of a string or binary object or -1 for any other atomic value
• There is a typeof operator to get a type id for any object

• Variables:

• Integers are not equivalent to booleans. Use the bool type


• There is just one kind of numbers: 32-bits signed integers
• Strings are primitive objects (of type str)
• All variables are implicitely initialized to a zero-like value
• C-like pointers are not available, but the var type can be used to store the
reference to an objects
• Enumerated values are not handled as constants but as strings
• Arrays declared without declared size are auto-growing arrays
• Array and structure initializers do not need to be constant
• There are no unions

21
Chapter 3. Library Functions

This chapter describes in details the basic functions available in REMBO to perform
simple operations. They are roughly equivalent to the standard library available with
most languages. Most of them are built-in primitives, and a few others are preloaded
as part of the standard utilitary plug-ins.

3.1. Library functions by category


Table 3-1. String manipulations

Strf Format a message in a string


StrLength Answer the character length of a string
StrFind Find the occurrence of a string within
another
StrFindCI Find the occurrence of a case-insensitive
string within another
StrParse Split a string into pieces for given
separators
StrCopy Duplicate a fragment of a string
StrDelete Delete a fragment of a string
StrInsert Insert a new fragment in a string
StrTrim Remove leading and trailing spaces (and
quotes)
StrCompare Compare two strings (case-sensitive)
StrCompareCI Compare two strings (case-insensitive)
StrMatch Wildcard match (globbing),
case-sensitive
StrMatchCI Wildcard match (globbing),
case-insensitive
StrChDir Compute a normalized path
StrGetFileName Extract the filename from a path
StrGetFileExt Extract the extension from a filename
StrPatch Substitute variable expressions in a
string
StrToUpper Retrieve the uppercase representation of
a string
StrToLower Retrieve the lowercase representation of
a string

22
Chapter 3. Library Functions

StrToHTML Encode a string to a HTML 7-bits buffer


StrFromCP (FromCodepage) Get a string from a 8-bits
codepage-encoded buffer
StrToCP (ToCodepage) Encode a string to a 8-bits
codepage-encoded buffer
StrFromUCS (FromUnicode) Get a string from a 16-bits unicode
buffer
StrToUCS (ToUnicode) Encode a string to a 16-bits unicode
buffer
StrFromUTF8 (FromUTF8) Get a string from a UTF8-encoded
unicode buffer
StrToUTF8 (ToUTF8) Encode a string to a UTF8-encoded
unicode buffer
SizeToStr Retrieve the string representation of a
numerical size
DateFromInt Retrieve the string representation of a
numerical date

Table 3-2. Binary objects manipulations

BinCreate Create a binary object


BinFromHex (FromHex) Build a binary object from its
hexadecimal representation
BinToHex (ToHex) Convert a binary object to its
hexadecimal representation
BinFromStr Build a binary object encoding a string
BinToStr Convert a binary object to a string
BinFromInt Build a binary object encoding a number

BinToInt Convert a binary buffer to an integer


BinGetInt Extract a signed number from a binary
object
BinGetUInt Extract an unsigned number from a
binary object
BinGetStr Extract a string from a binary object
BinGetBin Extract a subrange from a binary object
BinSetInt Patch a binary object with a number
BinSetStr Patch a binary object with a string
BinSetBin Patch a binary object with another
binary object

23
Chapter 3. Library Functions

BinFill Fill a binary object with a repeated byte


BinEFind Find a binary object in another binary
object (extended version)
BinReplace Find and replace a binary sequence in a
binary object
BinSetRandom Fill a binary object with random data
BinGetLine Extract a line of text from a binary
object
BinGetNextLinePtr Get the offset of the next line of text

Table 3-3. Array and structure manipulations

DeepCopy Recursively duplicate a structured


variable
DeepFreeze Recursively protect a structured variable
EnumKeys Retrieve the array of possible values for
an enumerated variable
StructKeys Answer the array of keys of a structure
StructRef Retrieve a member of a structure

Table 3-4. Directory manipulations

CreateDir (MkDir) Create a new directory


RenameDir Change the name of an existing
directory
RemoveDir (RmDir) Delete an empty directory
CopyTree Recursively copy a directory and its
content
MoveTree Move a file or directory and its content
RemoveTree (DelTree) Recursively destroy a directory and its
content
ChDir Change the default working directory
LoadDir Load a directory
LoadDirMatch Load a directory

Table 3-5. File manipulations

CopyFile (FileCopy) Copy any kind of file


PatchFile Copy a text file, replacing expressions
on the fly

24
Chapter 3. Library Functions

FileDiff Compare two text files and extract the


differences
FilePatch Patch a text file with previously
extracted differences
RenameFile (FileRename) Change the name of a file
RemoveFile (FileUnlink) Delete an existing file
FileLink Create a hard-link
SymLink Create a linux symbolic link
FileExists Test for the existence of a file or
directory
FileStat Answer file status informations
FileGetAttribute Retrieve filesystem-specific file
attributes
FileSetAttribute Change filesystem-specific file attributes

Table 3-6. File contents manipulation

CreateTextFile (SaveText) Create a text file (codepage encoded)


CreateUnicodeFile Create an unicode file
CreateMultiUniFile Create a multi-valued unicode file
CreateUTF8File Create an UTF8 file
CreateHexFile Create a text file containing the hex
string of a binary buffer
CreateBinaryFile (SaveFile) Create a binary file
CreateStrFile Create a file containing a Rembo
unicode string
LoadTextFile (LoadText) Load a text file (codepage encoded)
LoadUnicodeFile Load an unicode text file
LoadMultiUniFile Load an multi-valued unicode file
LoadUTF8File Load an UTF8 text file
LoadHexFile Load a text file containing an hex string
into a binary buffer
LoadBinaryFile (LoadFile) Load a file in a binary buffer
FileOpen Open a file
FileRead Read a binary object from a file
FileWrite Write a binary object to a file
FileSize Answer the file size in bytes
FileSetSize Resize a file to the specified size

25
Chapter 3. Library Functions

FileTell Answer the current file pointer absolute


position
FileSeek Move the file pointer to an absolute
position
FileSkip Move the file pointer to a relative
position
FileWriteFrom Copy the content of a file to another
FileClose Close an open file

Table 3-7. User interface manipulations

OpenWindow Open a new window


Window Retrieve a window widget
HideWindow Hide a window without closing it
ShowWindow Show a previously hidden window
CloseWindow Close a window
ResizeWindow Change the size of a window
AutoResizeWindow Automatically resize a window
MakeWindow Create a window of an optimal size for a
given content
ApplyStyle Apply a stylesheet to a window
Widget Retrieve a widget object from its path
WidgetNamed Retrieve a widget object from its name
ScreenShot Save the content of the display in a file
LoadCursor Load a graphic cursor
ScreenSaver Function called when screen saver is
activated
ScreenSaverExit Function called when screen saver is
deactivated
Browse Function called to browse an arbitrary
file
Beep Generate a sound using the PC speaker

Table 3-8. Evaluation-related primitives

Exec Load and execute a Rembo-C script in a


new thread
Eval Evaluate a Rembo-C expression in a
new thread

26
Chapter 3. Library Functions

WinEval Evaluate a Rembo-C expression in a


contexted thread
KillThread Kill thread if it is still alive
RaiseError Trigger an exception
DefaultExceptionHandler Default exception handler
LogVar Display any kind of variable on the
console log window
GlobalVars Retrieve an array of global variables
matching a pattern

Table 3-9. Persistent Variables

Export Make a variable persistent


UnExport Remove an export declaration
VarToExpr Answer a script expression for a given
variable value

Table 3-10. Network-related primitives

NetFile Find a host-specific, group-specific or


global file
NetFullPath Retrieve the global network path for a
given scope
CachedFileStat Retrieve the status of a file stored in the
cache partition
RemoveCachedFile Remove a file from the cache partition
SysLog Send a message to the server log
SysLogF Send a message to a custom server log
DownloadFile Download a file in multicast without
using the hard-disk
Download Download a file from the server with the
MCAST protocol
FileDownloadInProgress Answer true iff there is an ongoing
MCAST download for a specified file
MetaCast Run a MetaCast synchronized transfer
(deprecated)
BatchTransfer Run a multiple file transfer
CopyCache Preload a cache partition
GetLock Acquire a named lock on the server for
synchronization
ReleaseLock Release a named lock on the server

27
Table 3-11. System primitives

Interact Bring an interactive evaluator window


ShowConsole Show the console log window
HideConsole Hide the console log window
Print (Log) Display text on the console window
Printf Format text on the console window
FatalError Trigger a fatal error, stop REMBO
GarbageCollect Force memory garbage collection
FlushAll (Flush) Commit to disk all cached data
Keyb (LoadKeyMap) Change the keyboard mapping
CodePage (LoadCodePage) Change the active codepage
Time Retrieve the current value of the internal
time counter
GetMemoryInfo Retrieve information about the system
memory usage
GetNetStats Retrieve statistics from the network
interface
GeneratePassword Generate a random password
FileTest Perform a full read test on a device
LogDir Dump the content of a directory to the
console log
ViewDir Open a directory browser dialog
CMOSRead Read data from the CMOS memory
CMOSWrite Write data to the CMOS memory

3.2. String manipulations

Strf
Strf — Format a message in a string
Synopsis

Defined in
Built-in function.

Function prototype

str Strf(str format, ...);

28
Strf

Description
This function builds a string made of heterogeneous elements. The string is
formatted according to the rules specified in format.
Strf accepts a series of arguments, applies to each a format specifier contained in
the format string and returns the formatted data.
Strf applies the first format specifier to the first argument, the second to the second,
and so on. There must be the same number of format specifiers as arguments.
The following format specifiers are supported by Strf:

• %X: insert the uppercase representation of a numerical expression.


• %x: insert the lowercase representation of a numerical expression.
• %u: insert the unsigned decimal representation of a numerical expression.
• %d (or %i): insert the signed decimal representation of a numerical variable.
• %s: insert a string expression.
• %b: insert the textual representation (true/false) of a boolean expression.

Format specifiers can be preceded with a numerical value to ensure a minimum size
for the textual representation of the corresponding expression. If the representation
is smaller than the specified size, space characters are added before the expression.
If the size starts with 0, the character ’0’ is used instead of spaces for padding. And
if the size is preceded by -, then the padding occurs after the expression.

Examples
Let the following variables be defined:
int ta = 5, tb = 6;
str ts = "teststring";
bool tc = false;

Here is a list of usage examples:


Strf("%d",5)
= "5"
Strf("%d",ta+5)
= "10"
Strf("%d sampletext %d",ta,ta*tb)
= "5 sampletext 30"

29
Strf
Strf("%d [%s] %d, %b",StrLength(ts),ts,tb,tc)
= "10 [teststring] 6, false"

30
StrLength
StrLength — Answer the character length of a string
Synopsis

Defined in
Built-in function.

Function prototype

int StrLength(str text);

Description
This functions returns the length of a string (i.e. the number of characters).
This function is equivalent to the sizeof() operator used on a string object.

Examples
Let the following variables be defined:
str teststring = "This is a test";
str anotherstr = "Another";

Here is a list of usage examples:


StrLength("abcd")
= 4
StrLength("abcd")*10
= 40
StrLength(teststring)
= 14
StrLength(anotherstr)+StrLength(teststring)
= 21
StrLength(anotherstr+teststring)
= 21
sizeof(anotherstr)
= 7

31
StrFind
StrFind — Find the occurrence of a string within another
Synopsis

Defined in
Built-in function.

Function prototype

int StrFind(str text, str target);

Description
This function returns the index of the first occurence of the string target in the
string text. If no occurence is found, StrFind returns -1. Otherwise, the index is
relative to the start of the text string, beginning with index 0 (i.e. index 0 is
returned of text begins with an occurence of target).

Examples
Let the following variables be defined:
str st1 = "Hello world";
str st2 = "This is a test";
str st3 = "world";

Here is a list of usage examples:


StrFind(st1,"llo")
= 2
StrFind(st1,st3)
= 6
StrFind(st2,"is")
= 2
StrFind(st2,"testing")
= -1
StrFind(st1,"abcd")
= -1
StrFind("abcd","cd")
= 2

32
StrFind
See also
See also StrFindCI.

33
StrFindCI
StrFindCI — Find the occurrence of a case-insensitive string within another
Synopsis

Defined in
Built-in function.

Function prototype

int StrFindCI(str text, str target);

Description
This function returns the index of the first occurence of the string target in the
string text, without differentiating lower case and upper case characters. If no
occurence is found, StrFindCI returns -1. Otherwise, the index is relative to the
start of the text string, beginning with index 0 (i.e. index 0 is returned of text
begins with an occurence of target).

Example
StrFindCI("Hello world","LO")
= 3
StrFindCI("Hello world","LE")
= -1

See also
See also StrFind.

34
StrParse
StrParse — Split a string into pieces for given separators
Synopsis

Defined in
Built-in function.

Function prototype

var StrParse(str text, str sep);

Description
This function returns an array of strings built by separating the string text in
distinct elements using the characters in sep as the separators. The first element
(word) is stored at array index 0.
The most common usage is to call StrParse on a sentence, using " " as the
separator. The returned array will contain one word per array element. You can then
use the sizeof() operator on the array to determine the number of words in the
sentence.
The separators strings can contain one or more characters. Each of the characters
contained in the separators string will be used to split the input string in smaller
chunks. For example, if you have loaded a text file in a string with LoadTextFile(),
you build an array containing all the lines with
StrParse(filecontent,"\r\n"); (this will work for both MS-DOS and
Unix files).

Examples
Let the following variables be defined:
str st1 = "Hello world";
str st2 = "NTFS:1212 BIGDOS:1313"
str st3 = "word1;word2;word3";
var array = StrParse(st2," ");

Here is a list of usage examples:


StrParse(st1," ")
= an array of two elements:
{ "Hello", "world" }

35
StrParse
StrParse(st2,":")
= an array of three elements:
{ "NTFS", "1212 BIGDOS", "1313" }
StrParse(st2,": ")
= an array of four elements:
{ "NTFS", "1212", "BIGDOS", "1313" }
StrParse(st3,";")
= an array of three elements
{ "word1", "word2", "word3" }
sizeof(array)
= 2
array[0]
= "NTFS:1212"
StrParse(array[1],":")
= an array of two elements
{ "BIGDOS", "1313" }
(int)StrParse(StrParse(st2," ")[0],":")[1]
= 1212

36
StrCopy
StrCopy — Duplicate a fragment of a string
Synopsis

Defined in
Built-in function.

Function prototype

str StrCopy(str text, int pos, int stop);

Description
This functions builds a new string from a region of the string text. The region
starts at the index value pos and ends at the index value stop.
You can use this function to extract a part of a string. The index values are relative
to the beginning of the text string, and begin at index 0. The stop index is the
position of the first character not to be included in the resulting string.

Examples
Let the following variables be defined:
str st1 = "Hello world";
str st2 = "This is a test"

Here is a list of usage examples:


StrCopy(st1,0,3)
= "Hel"
StrCopy(st1,1,3)
= "el"
StrCopy(st2,5,7)
= "is"
StrCopy(st1,StrFind(st1,"world"),2)
= "wo"
st1 = StrCopy(st1,0,2)+StrCopy(st2,2,2);

37
StrDelete
StrDelete — Delete a fragment of a string
Synopsis

Defined in
Built-in function.

Function prototype

str StrDelete(str text, int pos, int stop);

Description
This functions builds a new string made of the text string with the region
[pos:stop] removed. The region starts at the index value pos and ends at the
index value stop. The character at stop is not included in the region to delete.
You can use this function to remove a part of a string. The index values are relative
to the beginning of the text string, and begin at index 0. The stop index is the
position of the first character not to be removed from the resulting string.

Examples
Let the following variables be defined:
str st1 = "Hello world";
str st2 = "This is a test"

Here is a list of usage examples:


StrDelete(st1,0,3)
= "lo world"
StrDelete(st1,1,3)
= "Hlo world"
StrDelete(st2,5,7)
= "This a test"
StrDelete(st1,StrFind(st1,"world"),2)
= "Hello rld"
st1 = StrDelete(st1,0,2);

38
StrInsert
StrInsert — Insert a new fragment in a string
Synopsis

Defined in
Built-in function.

Function prototype

str StrInsert(str text, int pos, str insert);

Description
This functions builds a new string made of the text string with the string insert
inserted at the position pos.
You can use this function to insert a string in another string. The index value is
relative to the beginning of the text string, and begin at index 0.

Examples
Let the following variables be defined:
str st1 = "Hello world";
str st2 = "This is a test"

Here is a list of usage examples:


StrInsert(st1,0,"!!")
= "!!Hello world"
StrInsert(st1,2,"!!")
= "He!!llo world"
StrInsert(st2,8,"not ");
= "This is not a test"
StrInsert(StrInsert(st1,StrLength(st1),"]"),0,"[")
= "[Hello world]"
st2 = StrInsert(st2,0,"+++");

39
StrTrim
StrTrim — Remove leading and trailing spaces (and quotes)
Synopsis

Defined in
plugins/utils.rbx

Function prototype

str StrTrim(str text);

Description
This functions returns a substring of text, obtained by removing all leading and
trailing spaces. In addition, if the first and last characters of the resulting string are
double-quotes, these are removed too.

Examples
str st1 = " Ole!";
str st2 = " \" Ole!\" ";

str trim1 = StrTrim(st1)


// trim1 = "Ole!"
str trim2 = StrTrim(st2)
// trim2 = " Ole!"

40
StrCompare
StrCompare — Compare two strings (case-sensitive)
Synopsis

Defined in
Built-in function.

Function prototype

int StrCompare(str str1, str str2);

Description
This function compares two strings and returns

• -1 if str1 < str2


• 0 if str1 == str2
• >1 if str1 > str2

The comparison is case-sensitive.

Example
Here is the implementation of this function in Rembo-C:
int StrCompare(str sa, str sb)
{
if (sa>sb) return 1;
else
if (sa==sb) return 0;
else
return -1;
}

41
StrCompareCI
StrCompareCI — Compare two strings (case-insensitive)
Synopsis

Defined in
Built-in function.

Function prototype

int StrCompareCI(str str1, str str2);

Description
This function compares two strings and returns

• -1 if str1 < str2


• 0 if str1 == str2
• >1 if str1 > str2

The comparison is case-insensitive.

Example
Here is the implementation of this function in Rembo-C:
int StrCompareCI(str sa, str sb)
{
str lsa = StrToUpper(sa);
str lsb = StrToUpper(sb);
if (lsa>lsb) return 1;
else
if (lsa==lsb) return 0;
else
return -1;
}

42
StrMatch
StrMatch — Wildcard match (globbing), case-sensitive
Synopsis

Defined in
Built-in function.

Function prototype

bool StrMatch(str text, str pattern);

Description
This function tries to match the string text with a give pattern (a wildcard). If the
string matches the pattern, the function returns true. Otherwise it returns false.
The pattern works like a file wildcard in MS-DOS or Unix: you can use the ’*’ and
’?’ to match any number of characters, or one character respectively.

For example, the pattern "test*" will match any string starting with "test". The
pattern "test*abcd" will match any string starting with "test" and ending with
"abcd". And the pattern "file?" will match any string of four characters starting
with "file" (? only match one character, while * matches one or more characters).
The matching is case-sensitive.

Examples
Examples of pattern-matching:
StrMatch("mouse and cat","mouse*")
= true
StrMatch("mouse and cat","*cat")
= true
StrMatch("mouse and cat","cat*mouse")
= false
StrMatch("mouse and cat","mouse*cat")
= true
StrMatch("foleafolea","f?le*")
= true
StrMatch("aoleafolea","f?le*")
= false

43
StrMatchCI
StrMatchCI — Wildcard match (globbing), case-insensitive
Synopsis

Defined in
Built-in function.

Function prototype

bool StrMatchCI(str text, str expr);

Description
This functions is the case-insensitive version of StrMatch().
See the manual page of StrMatch for more information.

44
StrChDir
StrChDir — Compute a normalized path
Synopsis

Defined in
Built-in function.

Function prototype

str StrChDir(str basepath, str relpath);

Description
This function returns a string representing the concatenation of the path basepath
with the relative path relpath. The relative path can contain complex paths
elements like ".." or "./".
StrChDir will not check the existence of the resulting path (i.e. it will not check
wheter this path maps to an existing file or directory). You can use FileExists to
check the existence of a path (a file or a directory).

Examples
Example of function usage:
StrChDir("net://global","test")
= "net://global/test"
StrChDir("net://global/test","newtest")
= "net://global/test/newtest"
StrChDir("net://global/test","../newtest")
= "net://global/newtest"
StrChDir("net://global/test/newtest","../../newtest/test")
= "net://global/newtest/test"

45
StrGetFileExt
StrGetFileExt — Extract the extension from a filename
Synopsis

Defined in
Built-in function.

Function prototype

str StrGetFileExt(str filename);

Description
This function returns the extension part of a path, or an empty string if the given
path has no extension.

Examples
Example of function usage:
StrGetFileExt("command.com")
= "com"
StrGetFileExt("command")
= ""
StrGetFileExt("newfile.html")
= "html"
StrGetFileExt("net://global/newfile.html")
= "html"

46
StrGetFileName
StrGetFileName — Extract the filename from a path
Synopsis

Defined in
Built-in function.

Function prototype

str StrGetFileName(str path);

Description
This function returns the last element of a path (i.e. the filename if the path points to
a filename, or the directory name if the path points to a directory).

Examples
Example of function usage:
StrGetFileName("command.com")
= "command.com"
StrGetFileName("net://global/command")
= "command"
StrGetFileName("disk://0:1/windows/command.com")
= "command.com"

47
StrPatch
StrPatch — Substitute variable expressions in a string
Synopsis

Defined in
plugins/utils.rbx

Function prototype

str StrPatch(str text);

Description
This function applies patch expressions to the given string and returns the resulting
string. Patch expressions are a set of rules which are interpreted by this function and
replaced by their value.
Patch expressions start with the character { and end with }. Words between these
two characters are interpreted by REMBO using one of the following schemes:

• {$expr$} the expression is replaced with the string resulting of the evaluation of
expr.

• {/expr/ab} the expression is replaced with the string resulting of the evaluation of
expr, but each occurence of the character "a" is replaced by the character "b"
(character-based substitution).
• {+expr+this is a test} the text "this is a test" is included in the destination
file only if the expression expr is evaluated without error (e.g. variable exists).
• {-expr-this is a test} the text "this is a test" is included in the destination file
only if the expression expr returns an error on evaluation (e.g. variable does not
exist).
• {=expr=test content=this is a test} the text "this is a test" is included in the
destination file only if the string resulting of the evaluation of expr is equal to the
text "test content".
• {!expr!test content!this is a test} the text "this is a test" is included in the
destination file only if the string resulting of the evaluation of expr is not equal to
the text "test content".

48
StrPatch
A patch expression cannot span multiple lines of the input files. The expression to
be evaluated (i.e. the first argument of the patch expression) can be a single variable
name, an array index or a structure member.
The function PatchFile uses StrPatch for file patching. See the manual page of
PatchFile for examples of patch expressions.
Note: PatchFile(filename) is equivalent to
StrPatch(LoadTextFile(filename)).

49
StrToUpper
StrToUpper — Retrieve the uppercase representation of a string
Synopsis

Defined in
Built-in function.

Function prototype

str StrToUpper(str text);

Description
This functions returns the uppercase representation of the give string.

Example
StrToUpper("abcd")
= "ABCD"
StrToUpper("AbCd")
= "ABCD"

50
StrToLower
StrToLower — Retrieve the lowercase representation of a string
Synopsis

Defined in
Built-in function.

Function prototype

str StrToLower(str text);

Description
This functions returns the lowercase representation of the give string.

Example
StrToLower("abcd")
= "abcd"
StrToLower("AbCd")
= "abcd"

51
StrToHTML
StrToHTML — Encode a string to a HTML 7-bits buffer
Synopsis

Defined in
Built-in function.

Function prototype

str StrToHTML(str text);

Description
This function prepares a string for use in a HTML display by replacing all HTML
reserved characters with their escape sequence. The returned string can be displayed
in a HTML window without being interpreted as HTML.
This function can be used to display the source code of a HTML page in a REMBO
window.

Example
Try the two following instructions and observe the difference:
Log("<font color=red>This text is red</font><br>");
Log(StrToHTML("<font color=red>This text is red</font><br>"));

52
StrFromCP
StrFromCP — Get a string from a 8-bits codepage-encoded buffer
Synopsis

Defined in
StrFromCP: Built-in function.
FromCodePage: /plugins/utils.rbx

Function prototype

str StrFromCP(var bincp);


str FromCodePage(var bincp);

Description
This function convert a codepage encoded buffer into a REMBO string. A codepage
encoded buffer is a sequence of 8bits characters, whose meaning is defined by the
active codepage.
The fonction LoadTextFile is equivalent to
StrFromCP(LoadBinaryFile(path));.
FromCodePage is an alias for StrFromCP.

See also
See also the CodePage function, CreateTextFile and LoadTextFile.

53
StrToCP
StrToCP — Encode a string to a 8-bits codepage-encoded buffer
Synopsis

Defined in
StrToCP: Built-in function.
ToCodePage: /plugins/utils.rbx

Function prototype

var StrToCP(str text);


var ToCodePage(str text);

Description
This function convert a REMBO string into a codepage encoded buffer. A codepage
encoded buffer is a sequence of 8bits characters, whose meaning is defined by the
active codepage.
The function CreateTextFile is equivalent to
CreateBinaryFile(StrToCP(content),path);.
ToCodePage is an alias for StrToCP.

See also
See also the CodePage function, CreateTextFile and LoadTextFile.

54
StrFromUCS
StrFromUCS — Get a string from a 16-bits unicode buffer
Synopsis

Defined in
StrFromUCS: Built-in function.
FromUnicode: /plugins/utils.rbx

Function prototype

str StrFromUCS(var binucs);


str FromUnicode(var binucs);

Description
This function converts an unicode (UCS-16) encoded buffer into a REMBO string.
An unicode encoded buffer is a sequence of 16bits unicode characters. Windows
NT uses unicode for strings stored in the registry.
The fonction LoadUnicodeFile is equivalent to
StrFromUCS(LoadBinaryFile(path));.
FromUnicode is an alias for StrFromUCS.

See also
See also LoadUnicodeFile and CreateUnicodeFile.

55
StrToUCS
StrToUCS — Encode a string to a 16-bits unicode buffer
Synopsis

Defined in
StrToUCS: Built-in function.
ToUnicode: /plugins/utils.rbx

Function prototype

var StrToUCS(str text);


var ToUnicode(str text);

Description
This function converts REMBO strings to unicode (UCS-16) encoded buffers. An
unicode encoded buffer is a sequence of 16bits unicode characters. Windows NT
uses unicode for strings stored in the registry.
The function CreateUnicodeFile is equivalent to
CreateBinaryFile(StrToUCS(content),path);.
ToUnicode is an alias for StrToUCS.

See also
See also LoadUnicodeFile and CreateUnicodeFile.

56
StrFromUTF8
StrFromUTF8 — Get a string from a UTF8-encoded unicode buffer
Synopsis

Defined in
StrFromUTF8: Built-in function.
FromUTF8: /plugins/utils.rbx

Function prototype

str StrFromUTF8(var binutf);


str FromUTF8(var binutf);

Description
This function convert an UTF-8 encoded buffer into a REMBO string. An UTF-8
encoded buffer is a sequence of variable size character. Web page generators for
foreign languages (asiatic languages) save HTML pages in UTF-8 encoded files.
The fonction LoadUTF8File is equivalent to
StrFromUTF8(LoadBinaryFile(path));.
FromUTF8 is an alias for StrFromUTF8.

See also
See also LoadUTF8File and CreateUTF8File.

57
StrToUTF8
StrToUTF8 — Encode a string to a UTF8-encoded unicode buffer
Synopsis

Defined in
StrToUTF8: Built-in function.
ToUTF8: /plugins/utils.rbx

Function prototype

var StrToUTF8(str text);


var ToUTF8(str text);

Description
This function convert REMBO strings to UTF-8 encoded buffers. An UTF-8
encoded buffer is a sequence of variable size character. Web page generators for
foreign languages (asiatic languages) save HTML pages in UTF-8 encoded files.
And the function CreateUTF8File is equivalent to
CreateBinaryFile(StrToUTF8(content),path);.
ToUTF8 is an alias for StrToUTF8.

See also
See also LoadUTF8File and CreateUTF8File.

58
SizeToStr
SizeToStr — Retrieve the string representation of a numerical size
Synopsis

Defined in
plugins/utils.rbx

Function prototype

str SizeToStr(int size);

Description
This function returns a convenient string representation for the given numerical
size. The size is converted in kilobytes, megabytes or gigabytes and a prefix is
added to indicate the unit.
The resulting string is never larger than 6 characters.

Example
SizeToStr(12)
= "12"
SizeToStr(262144)
= "256KB"
SizeToStr(16777216)
= "16MB"

59
DateFromInt
DateFromInt — Retrieve the string representation of a numerical date
Synopsis

Defined in
Built-in function.

Function prototype

str DateFromInt(int numdate);

Description
This function returns a string representation for the given numerical date. The
parameter numdate must be a valid numerical date, as returned when casting
SystemInfo.Date to an integer, or as used in Unix operating systems.

In some situations it may be better to store the numerical representation of a date


instead of its string representation. For example, comparing two dates is easier
when using numerical representation than with string representation. DateFromInt
can be used to transform the numerical date back into a textual representation.

Example
int now = (int)SystemInfo.Date;
Printf("Now is %s, but also %s<br>",
SystemInfo.Date,
DateFromInt(now));

60
3.3. Binary objects manipulations

BinCreate
BinCreate — Create a binary object
Synopsis

Defined in
Built-in function.

Function prototype

var BinCreate(int size, int initval);

Description
This function creates a new binary object of size bytes, and filled with the value
initval. The binary object can then be used in all binary-oriented primitives.
There are several different ways to create a binary object:

• With a call to BinCreate


• By reading a binary file with LoadFile
• By using a transformation function on an integer or string variable.

Examples
A binary object is always stored in a variable of type var:
var bin = BinCreate(10,0); // Create a 10 bytes buffer
BinFill(bin,0,9,1); // Fill with ’1’

61
BinFromHex
BinFromHex — Build a binary object from its hexadecimal representation
Synopsis

Defined in
BinFromHex: Built-in function.
FromHex: /plugins/utils.rbx

Function prototype

var BinFromHex(str bin);


var FromHex(str bin);

Description
This function can be used to convert a hexadecimal string into a binary buffer. The
string must contain a sequence of bytes in hexadecimal representation (e.g. 010AFE).
The fonction LoadHexFile is equivalent to
BinFromHex(LoadTextFile(path));.
FromHex is an alias for BinFromHex.

See also
See also CreateHexFile and LoadHexFile.

Example
var bin = BinFromHex("1214FEDE4C");

62
BinToHex
BinToHex — Convert a binary object to its hexadecimal representation
Synopsis

Defined in
BinToHex: Built-in function.
ToHex: /plugins/utils.rbx

Function prototype

str BinToHex(var bin);


str ToHex(var bin);

Description
This function can be used to convert a binary buffer into its hexadecimal
representation stored in a string. Bytes are stored in sequence, without space
between numbers.
The function CreateHexFile is equivalent to
CreateTextFile(BinToHex(content),path);.
ToHex is an alias for BinToHex.

See also
See also CreateHexFile and LoadHexFile.

Example
var bin=BinCreate(4,0);
BinSetInt(bin,0,4,512);
str txt=BinToHex(bin);
Log(txt);
--> "00020000"

63
BinFromStr
BinFromStr — Build a binary object encoding a string
Synopsis

Defined in
Built-in function.

Function prototype

var BinFromStr(str text);

Description
This function returns a binary buffer on a string. The string is copied as is in the
binary buffer.

Example
var bin = BinFromStr("ABC");
str txt = BinToHex(bin);
Log(txt);
--> "41424300"

64
BinToStr
BinToStr — Convert a binary object to a string
Synopsis

Defined in
Built-in function.

Function prototype

str BinToStr(var bin);

Description
This function returns a string from a binary buffer. The buffer should contain valid
ASCII character because no conversion is performed.

Example
var bin = BinCreate(1,65);
str txt = BinToStr(bin);
Log(txt);
--> "A"

65
BinFromInt
BinFromInt — Build a binary object encoding a number
Synopsis

Defined in
plugins/utils.rbx

Function prototype

var BinFromInt(int value);

Description
BinFromInt creates a binary buffer with the representation of the number given as
argument. The number is stored as an intel order 32 bits value (big-endian).
You can use this function to write values in DWORD files in the Windows NT
registry. See the reg: URL.
This function is equivalent to
var bin = BinCreate(4,0);
BinSetInt(bin,0,4,value);

Example
var bin = BinFromInt(12);
CreateBinaryFile("reg://ntreg/myvalue.dword",bin);

66
BinToInt
BinToInt — Convert a binary buffer to an integer
Synopsis

Defined in
plugins/utils.rbx

Function prototype

int BinToInt(var bin);

Description
BinToInt returns the integer value represented by the given binary buffer. The
buffer must contain a 32 bits value stored in Intel order (big-endian).
You can use this function to extract the value of a DWORD file in the Windows NT
registry. See the reg: URL.

Example
var bin = LoadBinaryFile("reg://ntreg/myvalue.dword");
int value = BinToInt(bin);

67
BinGetInt
BinGetInt — Extract a signed number from a binary object
Synopsis

Defined in
Built-in function.

Function prototype

int BinGetInt(var bin, int pos, int len);

Description
This function extracts an integer at a given position in a binary buffer. The
parameter pos is the position of the first byte to extract (position 0 is the first byte
of the buffer), and len is the number of bytes to extract (cannot be larger than 4).
The extracted bytes are padded to 4 bytes, and then interpreted as a 32 bits
big-endian integer value.

Example
var bin = BinFromHex("00045455");
int value = BinGetInt(bin,0,2);
Log(value);
--> 1024 (0x400)

68
BinGetUInt
BinGetUInt — Extract an unsigned number from a binary object
Synopsis

Defined in
Built-in function.

Function prototype

int BinGetUInt(var bin, int pos, int len);

Description
This function works as BinGetInt but interpret the extracted bytes as an unsigned
integer value instead of a signed integer value.
See the manual page of BinGetInt for more information.

69
BinGetStr
BinGetStr — Extract a string from a binary object
Synopsis

Defined in
Built-in function.

Function prototype

str BinGetStr(var bin, int pos, int len);

Description
This function extracts len bytes starting at position pos in the given binary buffer,
and store these bytes as is in a string. The bytes should correspond to ASCII
characters or the string might be corrupted.
The parameter pos is an index in the buffer, starting with index 0 (i.e. index 0 is
valid and corresponds to the first byte of the binary buffer).

Example
var bin = BinFromHex("41424344");
str txt = BinGetStr(bin,1,2);
Log(txt);
--> "BC"

70
BinGetBin
BinGetBin — Extract a subrange from a binary object
Synopsis

Defined in
Built-in function.

Function prototype

var BinGetBin(var bin, int pos, int len);

Description
This function extracts a region of a binary buffer and returns this region as a new
binary buffer. len bytes are copied.
The parameter pos is an index in the buffer, starting with index 0 (i.e. index 0 is
valid and corresponds to the first byte of the binary buffer).

Example
var bin = BinFromHex("41424344");
var newbin = BinGetBin(bin,2,2);
Log(BinToHex(newbin));
--> "4344"

71
BinSetInt
BinSetInt — Patch a binary object with a number
Synopsis

Defined in
Built-in function.

Function prototype

void BinSetInt(var bin, int pos, int len, int val);

Description
This function stores the 32 bits representation (big-endian) of the integer val in the
given binary buffer at position pos, and considering len bytes for storing the
value. The length parameter len cannot be larger than 4.
This function works as follow:

• The integer value val is converted to a 4 bytes binary buffer (big-endian


representation of the value)
• len bytes of this binary buffer are copied in the binary buffer bin at position
pos.

The parameter pos is an index in the buffer, starting with index 0 (i.e. index 0 is
valid and corresponds to the first byte of the binary buffer).

Example
var bin = BinCreate(4,0);
BinSetInt(bin,0,2,0x21222324);
Log(BinToHex(bin));
--> "24230000"

72
BinSetStr
BinSetStr — Patch a binary object with a string
Synopsis

Defined in
Built-in function.

Function prototype

void BinSetStr(var bin, int pos, int len, str txt);

Description
This function stores the string txt at position pos in the given binary buffer. If the
string is more than len bytes long, only the first len bytes are copied.
If the string is smaller than len bytes, it is padded with 00 before copying.
The parameter pos is an index in the buffer, starting with index 0 (i.e. index 0 is
valid and corresponds to the first byte of the binary buffer).

Example
var bin = BinCreate(4,0x55);
BinSetStr(bin,0,3,"AB");
Log(BinToHex(bin));
--> "41420055"

73
BinSetBin
BinSetBin — Patch a binary object with another binary object
Synopsis

Defined in
Built-in function.

Function prototype

void BinSetBin(var bin, int pos, int len, var subbin);

Description
This function writes a binary buffer in another binary buffer at the position pos for
len bytes. The binary buffer is truncated to len bytes if it is larger than len
bytes, or padded with 00 if it is smaller.
The parameter pos is an index in the buffer, starting with index 0 (i.e. index 0 is
valid and corresponds to the first byte of the binary buffer).

Example
var bin1 = BinCreate(4,0x55);
var bin2 = BinCreate(2,0x66);
BinSetBin(bin1,1,2,bin2);
Log(BinToHex(bin1));
--> "55666655"

74
BinFill
BinFill — Fill a binary object with a repeated byte
Synopsis

Defined in
Built-in function.

Function prototype

void BinFill(var bin, int pos, int len, int val);

Description
This function fills a region of len bytes in the given binary buffer, beginning at
position pos. The region is filled with bytes set to the value val.
The parameter pos is an index in the buffer, starting with index 0 (i.e. index 0 is
valid and corresponds to the first byte of the binary buffer).

Example
var bin = BinCreate(4,0x55);
BinFill(bin,1,2,0x66);
Log(BinToHex(bin));
--> "55666655"

75
BinFind
BinFind — Find a binary object in another binary object
Synopsis

Defined in
Built-in function.

Function prototype

int BinFind(var bin, var target);

Description
This function searches for a binary buffer in another binary buffer. It returns the
position of the first occurence of the target buffer in the bin buffer, or -1 if no
occurence was found.
This function is used by REMBO wizards to determine if the operating system
supports FAT32 (in case of Windows 95):
var bin = LoadBinaryFile("disk://0:1/io.sys");
if (BinEFind(bin,0,0,BinFromStr("FAT32 "),8)>=0)
fat32 = true;
else
fat32 = false;

BinFind(a,b); is equivalent to BinEFind(a,0,0,b,0);.

76
BinEFind
BinEFind — Find a binary object in another binary object (extended version)
Synopsis

Defined in
Built-in function.

Function prototype

int BinEFind(var bin, int pos, int len, var target, int tgtlen);

Description
This is an extended version of BinFind. This function allows you to specify a
starting position (pos), a search length (len), and a length for the matching pattern
target (tgtlen).
If either len or tgtlen is 0, it is automatically replaced with the total length of
bin or target, respectively.
BinFind(a,b); is equivalent to BinEFind(a,0,0,b,0);.

77
BinReplace
BinReplace — Find and replace a binary sequence in a binary object
Synopsis

Defined in
Built-in function.

Function prototype

int BinReplace(var bin, var target, var replacement);

Description
This function searches a binary buffer for a target sequence, and replaces all
occurences by a replacement sequence of the same size. BinReplace returns the
number of occurences replaced.
This function is used by REMBO SID manipulation functions to patch the registery
files.

78
BinSetRandom
BinSetRandom — Fill a binary object with random data
Synopsis

Defined in
Built-in function.

Function prototype

void BinSetRandom(var bin, int pos, int len);

Description
This function writes random bytes in a binary buffer, starting at position pos for
len bytes. The random bytes can then be used to generate a random string (for a
password), or a random number.
The parameter pos is an index in the buffer, starting with index 0 (i.e. index 0 is
valid and corresponds to the first byte of the binary buffer).
The random numbers generator used in REMBO is based on CRCs.

Example
var bin = BinCreate(4,0);
BinSetRandom(bin,0,4);
int random = BinToInt(bin);

79
BinGetLine
BinGetLine — Extract a line of text from a binary object
Synopsis

Defined in
Built-in function.

Function prototype

str BinGetLine(var bin, int ptr);

Description
This function retrieves a text line from a binary buffer, starting at position ptr.
BinGetLine scan all the bytes in the buffer (starting at ptr) and stops on a carriage
return (13) or a line-feed (10) character, or if the end of string is reached.
You can use this function in conjunction with BinGetNextLinePtr to extract all the
text lines in a binary buffer. Start by calling BinGetLine with ptr set to 0, then use
BinGetNextLinePtr to get the pointer to the next line, until BinGetNextLinePtr
returns 0.

Example
var bin = LoadBinaryFile("disk://0:1/autoexec.bat");
int ptr = 0;
do {
str line = BinGetLine(bin,ptr);
ptr = BinGetNextLinePtr(bin,ptr);
} while (ptr);

80
BinGetNextLinePtr
BinGetNextLinePtr — Get the offset of the next line of text
Synopsis

Defined in
Built-in function.

Function prototype

int BinGetNextLinePtr(var bin, int ptr);

Description
This function returns the position of the next text line in a buffer, given a starting
position (ptr).
This function should be used in conjunction with BinGetLine to extract text lines
from a binary buffer. See the manual page of BinGetLine for more information.

81
3.4. Array and structure manipulations

DeepCopy
DeepCopy — Recursively duplicate a structured variable
Synopsis

Defined in
Built-in function.

Function prototype

var DeepCopy(var obj);

Description
This function creates an exact copy of the given Rembo-C variable, even if the
variable is a complex variable containing arrays of structures, or nested arrays.
DeepCopy works by recursively scanning all the elements of the source variable.

Using DeepCopy is different than simply assigning a variable to another. In other


words, if var1 is a complex variable (e.g. an array), var var2=var1; is not
equivalent to var var2=DeepCopy(var1);. In the first case, var2 will be a reference
to the content of var1: if you modify an element of var1, the corresponding element
in var2 will also be modified.

Example
This example illustrates the difference between an assignation and a call to
DeepCopy.

int x[3];
for (int i=0;i<3;i++) x[i]=i+10;
var y = x;
var z = DeepCopy(x);
Print(x[1]);
--> 11
y[1] = 25;
Print(x[1]);
--> 25
Print(z[1]);
--> 11

82
DeepFreeze
DeepFreeze — Recursively protect a structured variable
Synopsis

Defined in
Built-in function.

Function prototype

var DeepFreeze(var any, bool rdonly);

Description
This function protects all the elements of the given variable. If the parameter
rdonly is set to false, the elements are type-protected (i.e. their type cannot be
modified). If rdonly is set to true, the elements are type-protected and set to
read-only mode (i.e. their content cannot be modified).
DeepFreeze applies the protection on all the elements of the variable. If the variable
is a complex combination of arrays and structure, all the elements will be set
recursively.

Example
int x[3];
for (int i=0;i<3;i++) x[i]=i+10;
x[1] = 22;
DeepFreeze(x,true);
x[1]= 44;
--> Error (variable is read-only)

83
EnumKeys
EnumKeys — Retrieve the array of possible values for an enumerated variable
Synopsis

Defined in
Built-in function.

Function prototype

var EnumKeys(var enumvar);

Description
This function builds an array with all the elements of a variable which type is enum.
Read Section 2.2 for information about the enum type.

Example
enum { a, b, c, d } en;
en = "c";
var enk = EnumKeys(en);
Log(sizeof(enk));
--> 4
Log(enk[1]);
--> "b"
LogVar(enk);
--> { "a","b","c","d" }

84
StructKeys
StructKeys — Answer the array of keys of a structure
Synopsis

Defined in
Built-in function.

Function prototype

var StructKeys(var structvar);

Description
This function builds an array with the members’ names of a variable which type is
struct.
You can use this function to determine which member are defined in a structure for
which you do not have the declaration (e.g. system global variables).

Example
var hi = StructKeys(NetInfo);
LogVar(hi);
--> { "MACAddress","IPAddress",
"SubnetMask","DefaultGateway" }
Log(NetInfo.SubnetMask);
--> 255.255.255.0

85
StructRef
StructRef — Retrieve a member of a structure
Synopsis

Defined in
Built-in function.

Function prototype

var StructRef(var structvar, str key);

Description
This function returns the variable referencing the member key of the structure
stored in the variable structvar.
Since StructRef(HostInfo,"HostID") is equivalent to HostInfo.HostID, there is
no interest to use this function as long as you know the name of the member at
compilation time. However, StructRef might be useful if you need to build the
name of the member dynamically, and then access this member (e.g. when
accessing a cell in a table widget variable).

Example
Let the following HTML code be defined in the window "tw".
<table name=tbl>
<tr><td>Col0Row0<td>Col0Row1
<tr><td>Col0Row1<td>Col1Row1
</table>

And here is a function that can be used to modify the content of one of the above
table cells dynamically:
void ChangeCell(int col, int row, str text)
{
var tbl = WidgetNamed("display://tw","tbl");
str member = Strf("r%dc%d",row,col);
var cell = StructRef(tbl,member);
cell.content = text;
}

86
3.5. Directory manipulations

CreateDir
CreateDir — Create a new directory
Synopsis

Defined in
CreateDir: /plugins/utils.rbx

MkDir: Built-in function.

Function prototype

void CreateDir(str path);


void MkDir(str path);

Description
CreateDir creates a new directory at the location specified by the parameter. The
parameter must be a valid URL. See Section 2.1 in REMBO Client Administration
Manual for a discussion on how to build valid URLs.
CreateDir is an alias for MkDir.

87
RenameDir
RenameDir — Change the name of an existing directory
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void RenameDir(str path, str newname);

Description
RenameDir changes the name of an existing directory. As the renamed directory is
necessarily a child of the same parent directory, the new name should not be a fully
qualified path. It is considered as an error to rename a directory to a name which is
already used in this directory.

Example

RenameDir("disk://0:1/windows/system","system.old");

See also
See also MoveTree.

88
RemoveDir
RemoveDir — Delete an empty directory
Synopsis

Defined in
RemoveDir: /plugins/utils.rbx

RmDir: Built-in function.

Function prototype

void RemoveDir(str path);


void RmDir(str path);

Description
RemoveDir works like the usual rmdir command. It destroys a directory, if and only
if the directory is empty. It is considered as an error to try to remove a directory that
does not exist.
RemoveDir is an alias for RmDir.

See also
See also RemoveTree.

89
CopyTree
CopyTree — Recursively copy a directory and its content
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void CopyTree(str srcpath, str dstpath);

Description
CopyTree copies the directory tree headed by srcpath to dstpath. The source
path and destination path must be valid URLs. See Section 2.1 in REMBO Client
Administration Manual for a discussion on how to build valid URLs. If dstpath
is an existing directory, the tree is copied into this directory. Otherwise, a new
directory is created.

Example

Assuming that the directory home/profile does not exist on the hard disk,
CopyTree("net://user/profile", "disk://0:1/home/");

has the same effect as


CreateDir("disk://0:1/home/profile");
CopyTree("net://user/profile", "disk://0:1/home/profile");

See also
See also MoveTree to move a full directory tree without making a copy of it.

90
MoveTree
MoveTree — Move a file or directory and its content
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void MoveTree(str srcpath, str dstpath);

Description
MoveTree prunes the directory tree headed by srcpath and grafts it to dstpath.
The source path and destination path must be valid URLs on the same device. See
Section 2.1 in REMBO Client Administration Manual for a discussion on how to
build valid URLs. If dstpath is an existing directory, the tree is moved into this
directory. Otherwise, a new directory is created.
MoveTree can also be used similarly to move a single file.

Example
MoveTree("disk://0:1/windows/temp/download",
"disk://0:1/temp");

See also
See also CopyTree to copy a full directory tree.

91
RemoveTree
RemoveTree — Recursively destroy a directory and its content
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void RemoveTree(str path);

Description
RemoveTree recursively destroys a directory and its content. It is considered as an
error to try to remove a directory that does not exist.

92
ChDir
ChDir — Change the default working directory
Synopsis

Defined in
Built-in function

Function prototype

void ChDir(str path);

Description
This functions changes the current directory path of REMBO. This path is used to
resolve relative paths in REMBO.

Example
ChDir("net://global/");
str fl = LoadTextFile("rembo.shtml");
--> fl is setup with the content of the file
"net://global/rembo.shtml

93
LoadDir
LoadDir — Load a directory
Synopsis

Defined in
Built-in function

Function prototype

var LoadDir(str path);

Description
This function loads all the entries of a given directory and builds an array of
mkdirent structures. Each element of the array correspond to a directory entry.

You can use the sizeof() on the array returned by LoadDir to determine the
number of entries in a directory.
The mkdirent structure is made of the following fields:

• str name: the filename of the directory entry;


• ftype type: the type of the entry, either "file", "dir" or "link";
• date modif: the last modification time;
• date creat: the creation time;
• int size: the size in bytes of the file associated with the directory entry (not
valid if the entry is a directory);
• int inodeid: the filesystem-specific record number for the file/directory
associated with this entry
• str md5: the MD5 hash for the file associated with this entry (valid for files on
net: and cache: only).

The structure members creat and modif are special variables used by REMBO to
represent dates. If you cast such a variable to an integer, the result will be a number
representing the date as the number of seconds elapsed since Jan 1, 1970 (Unix
time). But if you cast the variable to a string, the result will be a textual
representation of the date.

94
LoadDir
Example
Here is a simple LogDir function:
void LogDir(str path)
{
var dir = LoadDir(path);
Log("Directory "+path+" has "+(str)sizeof(dir)+" entries<br>&");
for (int i=0;i<sizeof(dir);i++)
Log(Strf("%-20s %15d %15s<br>&",
dir[i].name, dir[i].size, (str)dir[i].modif);
}

See also
See also LoadDirMatch to to retrieve only the files that match a given pattern.

95
LoadDirMatch
LoadDirMatch — Load a directory
Synopsis

Defined in
Built-in function

Function prototype

var LoadDirMatch(str path, str pattern, bool casei);

Description
This function loads all directory entries matching the given globbing pattern in
the given directory and builds an array of mkdirent structures. Each element of the
array correspond to a directory entry.
When the value of the parameter casei is true, the matching is case insensitive.
When the value is set to false, the matching is case sensitive.
For a complete description of the structure returned, you can see read the
description of the LoadDir function.

Example
LogVar(LoadDirMatch("disk://0:1","b*",true));

See also
See also LoadDir to copy a full directory tree.

96
3.6. File manipulations

CopyFile
CopyFile — Copy any kind of file
Synopsis

Defined in
CopyFile: /plugins/utils.rbx

FileCopy: Built-in function.

Function prototype

void CopyFile(str srcpath, str dstpath);


void FileCopy(str srcpath, str dstpath);

Description
CopyFile copies the file srcpath to a new file dstpath. The source path and
destination path must be valid URLs. See Section 2.1 in REMBO Client
Administration Manual for a discussion on how to build valid URLs. If dstpath
is a directory, the filename of the copied file is assumed to be the same as in
srcpath.
FileCopy is the low-level primitive used by CopyFile. FileCopy does not add the
filename at the end of the path if the second parameter is a directory.

Example
CopyFile("net://group/autoexec.bat",
"disk://0:1/autoexec.bat");

has the same effect as


CopyFile("net://group/autoexec.bat", "disk://0:1/");

See also
See also CopyTree to copy a full directory tree.

97
PatchFile
PatchFile — Copy a text file, replacing expressions on the fly
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void PatchFile(str srcpath, str dstpath);

Description
PatchFile copies srcpath to dstpath, replacing on the fly special tagged
expressions by their value. The format of patch expressions is the same as in SHTML
files. See below for a description of the patch expressions. The source path and
destination path must be valid URLs. See Section 2.1 in REMBO Client
Administration Manual for a discussion on how to build valid URLs.
You can use PatchFile to modify the operating system startup files by inserting
values received from the DHCP server. This is the technique used to modify the
computer name in Windows 98.
See the manual page of StrPatch for a detailed description of patch expressions.

Example

The destination file is disk://0:1/autoexec.bat, and the input file looks like:
@Echo off
set username={$AuthInfo.UserName$}
set hostname={$DHCPInfo.HostName$}
set spaceip={/NetInfo.IPAddress/. }
After executing PatchFile, the destination file will contain:
@Echo off
set username=john
set hostname=pcjohn
set spaceip=192 68 1 1

98
FileDiff
FileDiff — Compare two text files and extract the differences
Synopsis

Defined in
Built-in function.

Function prototype

int FileDiff(str file1, str file2, str patchfile, int ctxlines);

Description
FileDiff compares the two text files given as argument file1 and file2, and
builds a contextual difference file in patchfile that can be used to re-apply the
differences later. The number of context lines to use can be specified in ctxlines.
Using more context lines make the patch process more sure, since it will help to
ensure that the changes are done at the proper place, but it will also increase the
probability of having a patch completely rejected if the file to patch has slightly
changed in between.
The format of the resulting differential file is the same as used by the traditionnal
diff utility under Linux. However, in opposition to this powerful utility, this
function can only handle relatively small files.

Example

FileDiff("disk://0:1/autoexec.old",
"disk://0:1/autoexec.bat",
"disk://0:1/mychanges");

See also
See also FilePatch.

99
FilePatch
FilePatch — Patch a text file with previously extracted differences
Synopsis

Defined in
Built-in function.

Function prototype

void FilePatch(str srcfile, str patchfile, str dstfile);


void FilePatchEx(str srcfile, str patchfile, str dstfile, int
percentmatch);

Description
FilePatch analyzes the text file pointed by srcfile and tries to apply the
differential patches previously saved in patchfile. The resulting file is saved in
the file pointed by dstpath.
If the differential patches include context lines (which is usually the case, the
function does a careful optimization to find the best match. If a patch cannot be
matched, it may be rejected.
FilePatchEx performs the same kind of operation, but can apply patches on the
basis of a partially matched context.
The format of the input differential patch file is the same as used by the traditionnal
patch utility under Linux. However, in opposition to this powerful utility, this
function can only handle relatively small files.

Example

FilePatch("disk://0:1/autoexec.old",
"disk://0:1/mychanges",
"disk://0:1/autoexec.new");

is equivalent to

FilePatchEx("disk://0:1/autoexec.old",
"disk://0:1/mychanges",
"disk://0:1/autoexec.new",
100);

100
FilePatch
See also
See also FileDiff.

101
RenameFile
RenameFile — Change the name of a file
Synopsis

Defined in
RenameFile: /plugins/utils.rbx

FileRename: Built-in function.

Function prototype

void RenameFile(str path, str newname);


void FileRename(str oldpath, str newpath);

Description
RenameFile changes the name of an existing file. As the renamed file is necessarily
in the same directory, the new name should not be a fully qualified path. It is
considered as an error to rename a file to a name which is already used in this
directory.
FileRename is the low-level primitive used by RenameFile. FileRename requires the
two parameters to be fully qualified paths.

Example

RenameFile("disk://0:1/windows/win.ini","winini.old");

See also
See also MoveTree.

102
RemoveFile
RemoveFile — Delete an existing file
Synopsis

Defined in
RemoveFile: /plugins/utils.rbx

FileUnlink: Built-in function.

Function prototype

void RemoveFile(str path);


void FileUnlink(str path);

Description
RemoveFile deletes an existing file. It is considiered as an error to try to delete a file
that does not exist.
RemoveFile is an alias for FileUnlink.

See also
See also RemoveDir.

103
FileLink
FileLink — Create a hard-link
Synopsis

Defined in
Built-in function.

Function prototype

void FileLink(str linkpath, str target);

Description
This function creates a hard link to a target file. On filesystems supporting
hard-links (NTFS, EXT2FS), the FileLink function will simply create a new
directory entry pointing to the same file content as target. Note that you cannot
create hard-links on directories, and the linkpath and target paths must be
located on the same filesystem (i.e. disk partition).
If the linkpath parameter is a link: URL, FileLink will create a new entry
under the name linkpath on the LINK filesystem, and will make this entry point
to the file or directory specified by target. This can be used to link directories or
files to a LINK filesystem. The target can be any kind of REMBO valid URL (an
archive, a registry, or a disk file).
On a LINK filesystem, if the linkpath path already exists, FileLink will merge
the existing content of linkpath with the content of target recursively. If the
same file/directory exists in both linkpath and target, the original entry will
be replaced with the target entry.
Use FileLink in conjunction with CreateVirtualImage to create virtual images of
filesystems.

See also
See also the description page for net: urls and the manual page of
CreateVirtualImage.

Examples
To create a virtual image of a linux partition, and mount another partition on this
virtual image:
CreateVirtualImage("linux","disk://0:1"); // mount root

104
FileLink
LinkTree("link://linux/usr","disk://0:5"); // mount usr

To create a virtual image of a disk image (base image), and merge this image with
the content of another disk image (diff image):
OpenArchive("base","cache://global/ntbase");
CreateVirtualImage("nt","arch://base");
OpenArchive("diff","cache://global/ntdiff");
LinkTree("link://nt","arch://diff");

105
SymLink
SymLink — Create a linux symbolic link
Synopsis

Defined in
Built-in function.

Function prototype

void SymLink(str linkpath, str target);

Description
This function creates a symbolic link on a linux filesystem. The linkpath
specifies the name of the symlink to create, and must be a valid REMBO URL
referencing an EXT2 (linux) partition. The parameter target is relative to the
directory where the symbolic link is created, and must be a valid unix path (it will
be checked by linux, not by REMBO).

Examples
SymLink("disk://0:1/etc/X11/XF86Config",
"XF86config.aticard");
SymLink("disk://0:1/etc/hosts.allow",
"../usr/share/hostconfig/hosts.allow");
SymLink("disk://0:1/usr/tmp","/var/tmp");

106
FileExists
FileExists — Test for the existence of a file or directory
Synopsis

Defined in
Built-in function.

Function prototype

bool FileExists(str path);

Description
This functions returns true if and only if the given file exists.
You can use FileExists to check that a filesystem or device is open and readable
by checking whether FileExists returns true or false false when applied to the
root directory of the filesystem/device. Since no exception is generated if an error
occur, FileExists can be used to gracefully handle situations where a filesystem is
corrupted.

Example

The following commands displays OK in the console window if the file


disk://0:1/test exists, or NOT OK if it does not exist:

if(FileExists("disk://0:1/test"))
Print("OK");
else
Print("NOT OK");

107
FileStat
FileStat — Answer file status informations
Synopsis

Defined in
Built-in function.

Function prototype

var FileStat(str path);

Description
This function fetches information on the file or directory specified by the parameter
path and returns this information as a mkdirent structure.
See the manual page of LoadDir for a description of the mkdirent structure.

Example
var ino = FileStat("net://global/rembo.shtml");
Log("Size = "+(str)ino.size+"<br>&");

108
FileGetAttribute
FileGetAttribute — Retrieve filesystem-specific file attributes
Synopsis

Defined in
Built-in function.

Function prototype

var FileGetAttribute(str path);

Description
This function retrieve the filesystem-specific file attributes of the file designated by
the parameter path and returns this information as a binary object.
The binary buffer returned by FileGetAttribute should be used as opaque data, as
the internal encoding of the filesystem-specific attributes may be subject to changes.
However, it can safely be used as argument to function FileSetAttribute.

Example
MkDir("disk://0:1/newdir");
var attr = FileGetAttribute("disk://0:1/winnt");
FileSetAttribute("disk://0:1/newdir", attr);

109
FileSetAttribute
FileSetAttribute — Change filesystem-specific file attributes
Synopsis

Defined in
Built-in function.

Function prototype

void FileSetAttribute(str path, var attr);

Description
This function changes the filesystem-specific file attributes of the file designated by
the parameter path to the value stored in the binary object passed as parameter
attr.
Applications should only attribute buffers returned by FileGetAttribute as
argument to this function, or unpredictable side-effects may occur.

Example
MkDir("disk://0:1/newdir");
var attr = FileGetAttribute("disk://0:1/winnt");
FileSetAttribute("disk://0:1/newdir", attr);

110
3.7. File contents manipulation

CreateTextFile
CreateTextFile — Create a text file (codepage encoded)
Synopsis

Defined in
CreateTextFile: /plugins/utils.rbx

SaveText: Built-in function.

Function prototype

void CreateTextFile(str path, str content);

Description
CreateTextFile writes the given string to the file specified by the path parameter.
You can use this function to create simple text files. The string is encoded according
to the active codepage.
If the file already exists, CreateTextFile will overwrite the previous file content.
CreateTextFile is equivalent to SaveText.

Example

CreateTextFile("disk://0:1/flagfile","OK");

See also
See also CodePage, StrFromCP and StrToCP.

111
CreateUnicodeFile
CreateUnicodeFile — Create an unicode file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void CreateUnicodeFile(str path, str content);

Description
CreateUnicodeFile writes the given string to the file specified by the path
parameter. The string is encoded in unicode (UCS-16).
Use this function to modify Windows NT registry values of type string (.unicode).
If the file already exists, CreateUnicodeFile will overwrite the previous file
content.

Example

You can change the name of the current computer (Windows NT) by typing:
OpenRegistry("ntreg","disk://0:1/WINNT/system32/config/system");
CreateUnicodeFile("reg://ntreg/ControlSet001/Control/"
"ComputerName/ComputerName/ComputerName.unicode","NEWNAME");
CloseRegistry("ntreg");
FlushAll();

See also
See also StrFromUCS and StrToUCS.

112
CreateMultiUniFile
CreateMultiUniFile — Create a multi-valued unicode file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void CreateMultiUniFile(str path, var content);

Description
CreateMultiUniFile writes the given array of strings to the file specified by the
path parameter. The string is encoded in unicode (UCS-16), and the array
elements are separated by 16-bits NULL characters.
Use this function to modify Windows NT registry values of type "multiple strings"
(.multiuni).
If the file already exists, CreateMultiUniFile will overwrite the previous file
content.

See also
See also StrFromUCS and StrToUCS.

Example
str strings[2];
strings[0] = "First string";
strings[1] = "Second string";
CreateMultiUniFile("disk://0:1/testmuni",strings);

113
CreateUTF8File
CreateUTF8File — Create an UTF8 file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void CreateUTF8File(str path, str content);

Description
CreateUTF8File writes the given string to the file specified by the path parameter.
The string is encoded in UTF-8, a format supported by most modern internet
browser.
Use this function to create international (with unicode characters) HTML pages.
If the file already exists, CreateUTF8File will overwrite the previous file content.

See also
See also StrFromUTF8 and StrToUTF8.

114
CreateHexFile
CreateHexFile — Create a text file containing the hex string of a binary buffer
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void CreateHexFile(str path, var content);

Description
CreateHexFile writes the given binary buffer in a text file, converting the binary
information in a hexadecimal string.
Use this function to save binary buffer in a text file.
If the file already exists, CreateHexFile will overwrite the previous file content.

See also
See also BinFromHex and BinToHex.

115
CreateBinaryFile
CreateBinaryFile — Create a binary file
Synopsis

Defined in
CreateBinaryFile: /plugins/utils.rbx

SaveFile: Built-in function.

Function prototype

void CreateBinaryFile(str path, var content);


void SaveFile(var content, str path);

Description
CreateBinaryFile writes the content of the given binary buffer to the file specified
by the path parameter.
You can use this function to write binary values in a NT registry.
If the file already exists, CreateBinaryFile will overwrite the previous file content.
CreateBinaryFile is an alias for SaveFile.

Example
This example shows how to write an integer value in a file (can be used to write
.dword registry files).

int value = 12;


var bin = BinFromInt(value);
CreateBinaryFile("disk://0:1/testdw",bin);

116
CreateStrFile
CreateStrFile — Create a file containing a Rembo unicode string
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void CreateStrFile(str path, str content);

Description
CreateStrFile writes the given string in a binary file, using REMBO internal
packed unicode format.
Use this function to write an unicode string into REMBO display filesystem
(display URLs).

See also
See also BinFromStr and BinToStr.

117
LoadTextFile
LoadTextFile — Load a text file (codepage encoded)
Synopsis

Defined in
LoadTextFile: /plugins/utils.rbx

LoadText: Built-in function.

Function prototype

str LoadTextFile(str path);


str LoadText(str path);

Description
LoadTextFile loads the content of the given file in a string and returns the result.
The content of the file is interpreted according to the active codepage.
LoadTextFile is equivalent to LoadText.

See also
See also CreateTextFile, CodePage, StrFromCP, and StrToCP.

118
LoadUnicodeFile
LoadUnicodeFile — Load an unicode text file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str LoadUnicodeFile(str path);

Description
LoadUnicodeFile loads the content of the given file in a string and returns the
result. The content of the file must be a sequence of Unicode (UCS-16) characters.
Use LoadUnicodeFile to load string values in a Windows NT registry (.unicode).

See also
See also CreateUnicodeFile, StrFromUCS, and StrToUCS.

119
LoadMultiUniFile
LoadMultiUniFile — Load an multi-valued unicode file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var LoadMultiUniFile(str path);

Description
LoadMultiUniFile loads the content of the given file in an array of strings and
returns the result. The content of the file must be a set of Unicode strings (UCS-16),
separated by 16-bits nulls.
Use LoadMultiUniFile to load multiple string values from a Windows NT registry
(.multiuni).

See also
See also CreateMultiUniFile, StrFromUCS, and StrToUCS.

Example
var strings = LoadMultiUniFile("disk://0:1/munitest");
Print((str)sizeof(strings)+" strings found<br>");
for (int i=0;i<sizeof(strings);i++)
Print("Element "+(str)i+" is "+strings[i]+"<br>");

120
LoadUTF8File
LoadUTF8File — Load an UTF8 text file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str LoadUTF8File(str path);

Description
LoadUTF8File loads the content of the given file in a string and returns the result.
The content of the file must be a sequence of UTF-8 characters.

See also
See also CreateUTF8File, StrFromUTF8, and StrToUTF8.

121
LoadHexFile
LoadHexFile — Load a text file containing an hex string into a binary buffer
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var LoadHexFile(str path);

Description
LoadHexFile loads the content of the given file in a binary buffer. The file must
contain a hexadecimal string describing a binary buffer.
You can use this function to reload a binary buffer saved in a text file by
CreateHexFile.

See also
See also CreateHexFile, BinFromHex, and BinToHex.

122
LoadBinaryFile
LoadBinaryFile — Load a file in a binary buffer
Synopsis

Defined in
LoadBinaryFile: /plugins/utils.rbx

LoadFile: Built-in function.

Function prototype

var LoadBinaryFile(str path);


var LoadFile(str path);

Description
LoadBinaryFile returns the content of the given file as a binary buffer.
LoadBinaryFile is an alias for LoadFile.

See also
See also LoadTextFile, and CreateBinaryFile.

123
FileOpen
FileOpen — Open a file
Synopsis

Defined in
Built-in function.

Function prototype

var FileOpen(str path, str mode);

Description
This function opens the file specified by the URL path path. The parameter mode
is used to specify if the file must be open in read-only mode, in read-write mode or
in append mode.
If the file is successfully opened, FileOpen returns a variable containing the file
descriptor for the file. You can then use this variable in FileRead,FileWrite,
FileSize, FileTell, FileSeek, FileSkip, FileWriteForm and FileClose.

The file must be closed with FileClose when you do not need to use it anymore, or
data can stay uncomitted.
The mode parameter is a string of one or two characters, with the following valid
values:

• "r": the file is open for read-only operations;


• "r+": the file is open in read and write operations;
• "w":the file is truncated (i.e. its size is set to 0) if it already exists, or created if it
does not exist. The file is then opened for write-only operations;
• "w+": the file is truncated (i.e. its size is set to 0) if it already exists, or created if
it does not exist. The file is then opened for read and write operations;
• "a":the file is created if it does not exist, or opened in append mode (i.e. the file
pointer is set to the end of the file). The file is then opened for write-only
operations;
• "a+": the file is created if it does not exist, or opened in append mode (i.e. the
file pointer is set to the end of the file). The file is then opened for read and write
operations;

124
FileOpen
• "m": this is a special mode used by Download to open the MD5 sub-file instead of
the real file in case of a net:// file.

Example
var f = FileOpen("disk://0:1/autoexec.bat","r");
int sz = FileSize(f);
FileClose(f);
Log("Filesize is "+(str)sz+"<br>");

125
FileRead
FileRead — Read a binary object from a file
Synopsis

Defined in
Built-in function.

Function prototype

int FileRead(var file, var bin, int pos, int len);

Description
This function reads len bytes in the given file at the current file pointer position.
The data is stored in the binary buffer bin at the position pos. The binary buffer
must be large enough to hold len bytes at position pos.
The parameter file must be a file descriptor returned by FileOpen.
FileRead returns the number of bytes effectively read. If this value is smaller than
the parameter len, this usually means that the end of the file has been reached, or
an error occured.
The parameter pos is a position in the binary buffer, not in the file. If you want to
change the current position for the file, use FileSeek.

Example
This example shows how to read all the content of a file:
var f = FileOpen("disk://0:1/bigfile","r");
var bin = BinCreate(32768,0);
while (FileRead(f,bin,0,32768)==32768) {
// do something with data
}
FileClose(f);

126
FileWrite
FileWrite — Write a binary object to a file
Synopsis

Defined in
Built-in function.

Function prototype

int FileWrite(var file, var bin, int pos, int len);

Description
This function writes len bytes in the given file at the current file pointer position.
The data to write is read from the binary buffer bin at the position pos. There
must be at least len bytes available in the binary buffer at position pos.
The parameter file must be a file descriptor returned by FileOpen.
FileWrite returns the number of bytes effectively written. If this value is smaller
than the parameter len, this means that an error occured.
The parameter pos is a position in the binary buffer, not in the file. If you want to
change the current position for the file, use FileSeek.

Example
This example shows how to fill a file with 0s:
var f = FileOpen("disk://0:1/bigfile","r+");
var bin = BinCreate(32768,0);
int size = FileSize(f);
for (wrsize=0;wrsize<size;) {
int towrite = 32768;
if (wrsize+towrite>size)
towrite = size-wrsize;
FileWrite(f,bin,0,towrite);
wrsize += towrite;
}
FileClose(f);

127
FileSize
FileSize — Answer the file size in bytes
Synopsis

Defined in
Built-in function.

Function prototype

int FileSize(var file);

Description
This function returns the size in bytes of an opened file. This function does not
modify the state of the file descriptor (i.e. the current file pointer).
The parameter file must be a file descriptor returned by FileOpen.

Example
var f = FileOpen("disk://0:1/autoexec.bat","r");
int sz = FileSize(f);
FileClose(f);
Log("Filesize is "+(str)sz+"<br>");

128
FileSetSize
FileSetSize — Resize a file to the specified size
Synopsis

Defined in
Built-in function.

Function prototype

void FileSetSize(var file, int size);

Description
This function changes the size of the file given by an open file descriptor file. If
the file is shorter than size, additional blocs are preallocated and the file is
extended. If the file is bigger than size, it is truncated to the specified size.
The parameter file must be a file descriptor returned by FileOpen.

Example
To truncate a file to a null size, you could use:
var f = FileOpen("disk://0:1/config.sys","rw");
FileSetSize(f,0);
FileClose(f);

See also
See also FileOpen, FileSize.

129
FileTell
FileTell — Answer the current file pointer absolute position
Synopsis

Defined in
Built-in function.

Function prototype

int FileTell(var file);

Description
This functions returns the value of the current file pointer of the open file descriptor
file. The file pointer is the current position in the open file (for read and write
operations).
The parameter file must be a file descriptor returned by FileOpen.

Example
Seek 5 bytes forward:
int currpos = FileTell(f);
FileSeek(f,currpos+5);

130
FileSeek
FileSeek — Move the file pointer to an absolute position
Synopsis

Defined in
Built-in function.

Function prototype

void FileSeek(var file, int abspos);

Description
This function changes the value of the current file pointer for the open file file.
The file pointer is the current position in the open file (for read and write
operations). The abspos is an absolute position in bytes, relative to the beginning
of the file.
If the new position is beyond the current file size, the file is padded with NULL
bytes (0) up to the new size.
The parameter file must be a file descriptor returned by FileOpen.

Example
Seek 5 bytes forward:
int currpos = FileTell(f);
FileSeek(f,currpos+5);

131
FileSkip
FileSkip — Move the file pointer to a relative position
Synopsis

Defined in
Built-in function.

Function prototype

void FileSkip(var file, int relpos);

Description
This function moves the current file pointer relpos bytes forward (or backward if
relpos is a negative number).
The parameter file must be a file descriptor returned by FileOpen.
This function could be implemented by calling the functions FileTell and
FileSeek:
void FileSkip(var f, int relpos)
{
int currpos = FileTell(f);
currpos += relpos;
FileSeek(f,currpos);
}
shorter version:
void FileSkip(var f,int relpos) { FileSeek(FileTell(f)+relpos); }

132
FileWriteFrom
FileWriteFrom — Copy the content of a file to another
Synopsis

Defined in
Built-in function.

Function prototype

void FileWriteFrom(var file, str path, int buffsize);

Description
This function copies the content of the file specified by the parameter path (a valid
REMBO path) in the open file file, using a buffer of buffsize for reading and
writing operations.
The parameter file must be a file descriptor returned by FileOpen.
FileWriteFrom is equivalent to CopyFile, but with the additional requirement that
you must open the file manually before starting the copy operation. The advantage
of FileWriteFrom is that you can choose the size of the buffer used in the copy
operation (the value used by CopyFile is 256kb).

Example
Here is an implementation of CopyFile using FileWriteFrom
void FileCopy(str src, str dst)
{
var fdst = FileOpen(dst,"w");
FileWriteFrom(fdst,src,256*1024);
FileClose(fdst);
}

133
FileClose
FileClose — Close an open file
Synopsis

Defined in
Built-in function.

Function prototype

void FileClose(var file);

Description
This function closes a file descriptor previously opened with FileOpen.
You must use this function to close file descriptors, because open file descriptors
might keep some data uncommitted until the file is closed.

134
3.8. User interface manipulations

OpenWindow
OpenWindow — Open a new window
Synopsis

Defined in
Built-in function.

Function prototype

var OpenWindow(str win, int left, int top, int right, int bottom);

Description
This function opens a new window on the screen, and associates the name specified
by win with this new window. You can then use this name in all window-oriented
Rembo-C functions.
The parameters top, left, bottom and right are the absolute coordinates of
the new window on the screen. These coordinates must be specified in percent of
the total height/width of the screen.
OpenWindow returns a window structure, that can be used to modify the window
parameters, or to access the content of the window. See the manual page for
Window for more information about the window structure.

Example
var win = OpenWindow("tw",10,10,90,90);
win.widgets = "<title>My window</title>"
"<br>This is a test window<br>";

135
Window
Window — Retrieve a window widget
Synopsis

Defined in
Built-in function.

Function prototype

var Window(str name);

Description
This function retrieves the window structure corresponding to the window identified
by the string name. The parameter name must match the name of an existing
window, created with OpenWindow.
The window structure contains the following members:

• str name: the name of the window (as passed to OpenWindow);


• int top: the upper bound of the window on the screen, specified in percent of
the total screen height;
• int left: the left-most bound of the window on the screen, specified in percent
of the total screen width;
• int right: the right-most bound of the window on the screen, specified in
percent of the total screen width;
• int bottom: the bottom bound of the window on the screen, specified in percent
of the total screen height;
• bool visible: set to true if the window is visible, or false if it is hidden
(hidden windows still exist, but are not displayed on the screen). This value is set
to true (i.e. the window is visible) when the window is created;
• bool movable: set to true if the window can be moved with the mouse (the
default value is true);
• bool closable: set to true if the window can be closed by clicking on the cross
icon in the corner of the title bar or with Alt-F4. Set this member to false if you
want to prevent users to close this window (default value is true);
• bool resizable: set to true if the window can be resized with the mouse (the
default value is true);

136
Window
• bool alwaysOnTop: if set to true, the window will always stay on the top of all
other windows. The window thus cannot be masked by another window. This
value is initially set to false when the window is created;
• bool freezed: if set to true, all refresh operations on this window will be
suspended. The visual aspect of the window will stay unchanged even if its actual
content is dynamically modified. This value is set to false when the window is
created. You can use freezed to freeze the refresh process during an update of
several window elements at the same time. If freeze is set to false, REMBO
will redraw the window after each element modification, thus showing the update
process to the user. But if freeze is set to true during the update of the elements,
and then reset to false when all elements are updated, the user will only see the
final result of the update, and not the intermediate steps;
• str modalParent: this member can be used to specify a modal parent for this
window. A modal parent is a window which is completely inhibited during all the
time this window is open. The modal parent window cannot receive the focus
anymore, nor process any event until its modal child window is closed, or the
value of modalParent is changed in the modal child window’s structure. In
addition, the modal child window is always displayed on top of the modal parent
window (i.e. the modal parent cannot mask the modal child). Modal windows are
very useful when displaying input windows, which requires the user to input a
value to return to the main program (i.e. the modal parent). This value is initially
set to "" (no modal parent) when the window is created;
• var widgets: this members points to a structure referencing all the widgets (i.e.
window elements) contained in this window. If you write a string in this variable,
it will be interpreted as the HTML content of the window. Creating a window
usually involves two steps: a call to OpenWindow and a string assignation to
win.widgets.

Examples
Simple creation example:
var win = OpenWindow("tw",10,10,90,90);
win.visible = false; // Hide window
// setup content
win.widgets = "<title>My window</title>"
"<br>This is a test window<br>";
// show
win.visible = true;

Example of unmovable/unresizable window:

137
Window
var win = OpenWindow("tw",10,10,90,90);
win.visible = false; // Hide window
// setup content
win.widgets = "<title>My window</title>"
"<br>This is a test window<br>";
// resize
win.left = 20; win.right=80;
win.top = 20; win.bottom=80;
// make unmovable
win.movable=false;
// make unresizable
win.resizable=false;
// show
win.visible = true;

Example of freezed window:


// Get the window structure for existing window ’tw’
var win = Window("tw");
// Get the widget structure for the table ’tl’ in the
// window ’tw’
var tbl = WidgetNamed("display://tw","tl");
// Freeze the window
win.freezed=true;
// Update row 0, column 0
tbl.r0c0.value = "New content";
// Update row 0, column 1
tbl.r0c1.value = "Column 1";
// Unfreeze window
win.freezed=false;

138
HideWindow
HideWindow — Hide a window without closing it
Synopsis

Defined in
Built-in function.

Function prototype

void HideWindow(str win);

Description
This function hides a window from the screen. The window will no more be visible
on the screen, but it will still exist. Any oepration that can be performed on a visible
window can also be performed on a hidden window, but the result will not be visible
until the next call to ShowWindow.
You can use HideWindow to hide a window during a change on the layout of the
window (e.g. when you resize the window) and bring the window back on the
screen when the layout manager has replaced all the elements in the window. This
makes the update process faster and smoother (the user does not see the individual
update steps even if the computer is very slow).
The parameter win is the name of the window to show. This name must correspond
to an existing window, created with the OpenWindows function.
HideWindow is equivalent to
var win = Window(name);
win.visible = false;

Example
Window("testwin",10,10,80,80);
HideWindow("testwin");
ShowWindow("testwin");

139
ShowWindow
ShowWindow — Show a previously hidden window
Synopsis

Defined in
Built-in function.

Function prototype

void ShowWindow(str win);

Description
This function brings window previously hidden with HideWindows back on the
screen. It has no effect if the window is already visible.
The parameter win is the name of the window to show. This name must correspond
to an existing window, created with the OpenWindows function.
ShowWindow is equivalent to
var win = Window(name);
win.visible = true;

Example
Window("testwin",10,10,80,80);
HideWindow("testwin");
ShowWindow("testwin");

140
CloseWindow
CloseWindow — Close a window
Synopsis

Defined in
Built-in function.

Function prototype

void CloseWindow(str window);

Description
CloseWindow closes a window previously opened with OpenWindow (or any derivate
which uses OpenWindow, as OpenHTML or OpenMessage).
The parameter window must match the name given to OpenWindow when the
window was created.

See also
See also OpenWindow.

141
ResizeWindow
ResizeWindow — Change the size of a window
Synopsis

Defined in
Built-in function.

Function prototype

void ResizeWindow(str window, int left, int top, int right, int
bottom);

Description
ResizeWindow can be used to move and resize a window. The function takes as
argument the absolute coordinates of the four borders of the window, given in
percent of the total screen width/height. As a window must entirely fit on the screen,
the minimum value for all parameters is 0 and the maximal value is 100.
You can also modify the window structure members left, right, top and bottom to
resize a window:
void ResizeWindow(str name, int l, int r, int t, int b)
{
var win = Window(name);
win.visible=false; // do not show individual resize steps
win.left=l;
win.right=r;
win.top=t;
win.bottom=b;
win.visible=true;
}

Use the LogVar function to display the content of a window structure. This will
display the content of all members in the console log window.

Example

To center a window named banner on a third of the display width and height, use
ResizeWindow("banner",33,33,66,66);

142
ResizeWindow
See also
See also AutoResizeWindow.

143
AutoResizeWindow
AutoResizeWindow — Automatically resize a window
Synopsis

Defined in
Built-in function.

Function prototype

void AutoResizeWindow(str window, bool hresize, bool vresize);

Description
This function tries to determine the minimal size for a window, and shrinks the
window to match this minimal size. Before calling this function, set the window
size to the maximum size that you would like the window to be, using the
ResizeWindow function. You may want to hide the window before doing so, to avoid
the flickering effect.
The auto-resize feature can be applied to the left-right coordinates of the window
(horizontal auto-resize), to the top-bottom coordinates of the window (vertical
auto-resize), or to both dimensions (horizontal and vertical auto-resize). The
parameters hresize and (resp. vresize) is set to true when a horizontal (rep.
vertical) resize is requested.

See also
See also ResizeWindow.

144
MakeWindow
MakeWindow — Create a window of an optimal size for a given content
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void MakeWindow(str name, str content);

Description
This function creates a window of the given name, sets its content to the given
HTML content and automatically resize it to the optimal size. The resizing is
done while the window is hidden, to avoid flickering on the screen.

Example
MakeWindow("test","<title>My window</title>"
"<br>This is a test window<br>");

145
ApplyStyle
ApplyStyle — Apply a stylesheet to a window
Synopsis

Defined in
Built-in function.

Function prototype

void ApplyStyle(str window, str style);

Description
This function applies a new CSS (Cascading Style Sheet) to the window identified
with window. This new style will be effective for new content only (i.e. existing
window content will not be affected by this new style).
There is a default style sheet used in REMBO for new windows. It is stored in the
variable Settings.DefaultStyle and can be displayed with
Log(Settings.DefaultStyle);. If you change the default CSS style, it will only
apply for new windows. To change the style on existing windows, use ApplyStyle.

Example
str style = "BODY { background-color: white; }";
ApplyStyle("tw",style);

146
Widget
Widget — Retrieve a widget object from its path
Synopsis

Defined in
Built-in function.

Function prototype

var Widget(str wdgpath);

Description
This function retrieves the widget structure corresponding to the widget specified
by the DISPFS path wdgpath. You can use the function WidgetNamed to build
widget paths.
The members of the widget structures depend on the kind of widget described by
the structure. Here is the description of some fields you may encounter:

• title: in a border widget, this is the title of the window. When empty, the window
has no title bar.
• body: in a border widget, this points to the widget structure describing the
content of the window.
• vscroll: in a scrolled frame widget, this is the vertical scroll position, given in
pixels (or in rows for text mode). You can read and set this value to automatically
scroll canevas.
• hscroll: in a scrolled frame widget, this is the horizontal scroll position, given in
pixels (or in columns for text mode). You can read and set this value to
automatically scroll canevas.
• content: this points to the widget structure describing the nested content of the
widget (for frames, buttons, ...).
• color: this is the color used to paint the widget itself. You can assign it to any
valid HTML color string (by name or by RGB value). When read, this attribute
takes as value the RGB representation of the color (which might not exactly
match the assigned value as REMBO uses a 15-bits internal color encoding.
• bgcolor: this is the color used to paint the background of the widget, as
described for color. A special #transparent value is recognized, to apply no
painting at all.

147
Widget
• bgimage: this is the URL of an image to paint on the background of the widget.
• width: in a grid widget, this is the global width of the table
• wid n: in a grid widget, this is the width of the nth column. You can change this
value to dynamically resize the table, for instance to imitate a slider bar.
• hgt n: in a grid widget, this is the height of the nth row. You can change this
value to dynamically resize the table.
• bwid n: in a grid widget, this is the width of the nth border arounr columns.
• bhgt n: in a grid widget, this is the height of the nth border around rows.
• name: in an image widget, this is the URL of the target image. You can read and
set this value to dynamically change the image shown.
• visible: this attribute controls whether the widget is displayed or not. When not
visible, a widget takes the same space but is not shown (transparent). You can use
this attribute to dynamically show or hide images, without having to reload them
on each change.
• value: for input fields and single selection widgets, this is the editable value
displayed and stored by the widget. You can read and set this value.
• active: this attribute controls whether the widget will react to events or whether it
is disabled. This does usually not have any effect on its appearance, which can be
controlled separatly using other attributes (color).
• readonly: for input widgets, this attribute controls whether the user is allowed to
edit the content or not.
• checked: for check boxes and radio buttons, this attribute is set to "1" when the
option is checked and "0" otherwise.
• label: for a pop-up selection widget, this is the widget structure of the button
content.
• select: for a pop-up selection widget, this is the widget structure of the pop-up
selector.

Use the LogVar function to display the content of a widget. This will also help you
understand how the widget is structured and which members are accessible in the
structure. Here is an example:
var wdg = WidgetNamed("display://td","texta");
LogVar(wdg);
=> the full content of the texta widget attributes
will be displayed

148
WidgetNamed
WidgetNamed — Retrieve a widget object from its name
Synopsis

Defined in
Built-in function.

Function prototype

var WidgetNamed(str basepath, str wdgname);

Description
This function searches in a display: path (usually the root path of a window) for
the widget identified with the name wdgname. It returns a widget structure
describing the corresponding widget. See the manual page of Widget for a detailed
description of the widget structure.
Almost every HTML element in a window can have its own name, specified with
the HTML attribute NAME. If you give names to the buttons, input boxes, radio
buttons, textareas or tables, you will be able to retrieve a structure on any widget by
simply specifying the name of the widget and the name of the window to search the
widget in. Once you have a widget structure, you can modify widget attributes
dynamically (change the content, the color, make inactive, ...).
For example, if you have created a new window called ’td’, containing the
following HTML code:<textarea rows=5 cols=15 name=texta>, you can change
the content of the textarea at any time with:
var wdg = WidgetNamed("display://td","texta");
wdg.content.value = "This is a sample text";
// Set the scroll bar to 30 pixels from the start of
// the text (ignored if no scroll bar displayed)
wdg.vscroll = 30;

Use the LogVar function to display the content of a widget. This will also help you
understand how the widget is structured and which members are accessible in the
structure. Here is an example:
var wdg = WidgetNamed("display://td","texta");
LogVar(wdg);
=> the full content of the textarea widget attributes
will be displayed

149
WidgetNamed

150
ScreenShot
ScreenShot — Save the content of the display in a file
Synopsis

Defined in
Built-in function.

Function prototype

void ScreenShot(str destpath, int left, int top, int right, int
bottom);

Description
This function saves the content of the display in the rectangle defined by left,
top, right and bottom to the bitmap file specified by destpath. The function
always uses Windows uncompressed 24-bits BMP format, regardless of the
extension given to the file name.
Bounding box coordinates are specified in percents of the screen width and height.
You can retrieve the approximate size of a window by accessing the corresponding
fields in the Window structure. However, as this rounded value may not be the exact
size of the window, it is better to resize the window first, or to use a slightly larger
snapshot.
When the global setting Settings.AllowScreenShots is turned on, pressing
Shift-PrintScreen has the same effect as evaluating
ScreenShot("cache://global/snapshot.bmp", 0, 0, 100, 100);

and pressing Alt-PrintScreen results in taking a snapshot of the top window.

151
LoadCursor
LoadCursor — Load a graphic cursor
Synopsis

Defined in
Built-in function.

Function prototype

void LoadCursor(str curfilepath);

Description
This function loads a bitmap file to be used as the image for the mouse pointer. The
file must contain a windows compatible cursor bitmap (a .ico file). Animated
cursors are not supported.

152
ScreenSaver
ScreenSaver — Function called when screen saver is activated
Synopsis

Defined in
Built-in function (default stub)

Function prototype

void ScreenSaver(void);

Description
This function is called when no activity has been detected (mouse and keyboard)
during the time specified by the variable Settings.ScreenSaverDelay. If the
variable is set to 0, then this function is never called.
This function is executed in a new thread of execution.
By default, this function does nothing. You can reimplement this function in your
script to do custom actions when the screen saver delay is elapsed (e.g. turn the
computer or the screen off).
The variable Settings.ScreenSaverDelay contains the inactivity time required to
start the screen saver. This value is specified in 100th of seconds (i.e. a value of 100
means one second).
If there is a keyboard or mouse activity when the screen saver is active (i.e. after
ScreenSaver has been called), then the screen saver is killed if it is still alive (i.e. if
the ScreenSaver function is not yet completed), and ScreenSaverExit is called.

Example
This sample scripts reimplements the ScreenSaver function to power off the
computer when the screen saver becomes active. The screen saver delay is set to 3
minutes.
void ScreenSaver(void)
{
PowerOff();
}
Settings.ScreenSaverDelay=3*60*100;

153
ScreenSaverExit
ScreenSaverExit — Function called when screen saver is deactivated
Synopsis

Defined in
Built-in function (default stub)

Function prototype

void ScreenSaverExit(void);

Description
This function is called if there is an activity after the function ScreenSaver has been
called. This function must perform the tasks needed to restore the system in its state
prior to the call to ScreenSaver (e.g. turn the screen on again).
The default implementation for this function does nothing. If you reimplement the
ScreenSaver, you should also reimplement this function if the screen saver can be
interrupted to come back to normal operation mode.

Example
In this example, the ScreenSaverExit turns the screen on again:
void ScreenSaverExit(void)
{
LockScreen(false);
}

154
Browse
Browse — Function called to browse an arbitrary file
Synopsis

Defined in
Built-in function

Function prototype

void Browse(str url, str anchor, str widget);

Description
This function displays the content of the file url in the window described by the
display: path widget.

If the filename ends with the extension .html, the content of the file is simply
copied into the window. If the extension is .shtml, the content is first patched with
the StrPatch function and then copied into the window.
The parameter widget is the display: path to the widget in which you want to
display the file. To display the file in a window, use the path
display://windowname (replace windowname with the name of the window).

The parameter anchor can be used to specify a HTML anchor to browse in the
url file.
This function is used by REMBO in three situations:

• through a call to OpenHTML;


• to load the initial startpage (HostInfo.StartPage) on the deskop when REMBO
starts;
• when the user clicks on a HTML hyperlink (<A> tag).

You can reimplement the Browse if you want to customize the behaviour of
REMBO.

Example
OpenWindow("tw",10,10,90,90);
Browse("net://global/mypage.html","","display://tw");

155
Browse

156
Beep
Beep — Generate a sound using the PC speaker
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void Beep(int freq, int delay);

Description
This function can be used to generate a sound using the internal PC speaker. The
first parameter, freq is the frequence of the sound in Hz. For example, to generate a
dial-tone, set freq to 440. The second parameter is the duration of the sound, in
hundredth of second. For example, to generate a sound during one second, set this
parameter to 100.

Example
Beep(440,100); // one second #A (LA)

157
3.9. Evaluation-related primitives

Exec
Exec — Load and execute a Rembo-C script in a new thread
Synopsis

Defined in
Built-in function

Function prototype

int Exec(str rbxpath);

Description
This function loads and execute the given file. The file can be either a text file
containing Rembo-C statements, or a compiled RBX file.
Exec starts a new thread of execution with the content of the rbxpath file. The
thread identifier of the newly created thread is returned by Exec.If you need to use
functions or variables defined in the rbxpath file, you will have to use the join
keyword to wait for the thread to finish before continuing:
int pid = Exec("net://global/myvars.rbc"); // start thread
join(pid); // wait for the thread to finish
// ... use variables/functions defined in myvars.rbc

158
Eval
Eval — Evaluate a Rembo-C expression in a new thread
Synopsis

Defined in
Built-in function

Function prototype

int Eval(str expr);

Description
This function evaluates a Rembo-C statement in a new thread, and returns the
thread identifier for the new thread.
As for the function Exec, if you need to wait for the Rembo-C statement to be
finished, you have to use the join keyword on the thread identifier:
int pid = Eval("Settings.AutoBoot=true;");
join(pid); // wait on the statement evaluation

159
WinEval
WinEval — Evaluate a Rembo-C expression in a contexted thread
Synopsis

Defined in
Built-in function

Function prototype

int WinEval(str windowname, str expr);

Description
This function is equivalent to Eval in the fact that it creates a new thread and
executes the Rembo-C statement expr in the new thread. The thread identifier for
the new thread is returned.
The difference between Eval and WinEval is that the latter bind the thread to the
window specified by the parameter windowname. The thread will thus have access
to all the named widgets defined in the window (buttons, tables, ...) as local
variables.

Example
var win=OpenWindow("tw",10,10,80,80);
win.widgets="<title>Test window</title>"
"<button name=testbtn>Test button</button>";
AutoResizeWindow("tw");
WinEval("tw","testbtn.value=’New label’;testbtn.color=red;");

160
KillThread
KillThread — Kill thread if it is still alive
Synopsis

Defined in
Built-in function

Function prototype

void KillThread(int threadid);

Description
This function terminates a thread immediately. The parameter is the identifier of the
thread to kill. The thread must have been created with Exec, Eval or WinEval.

Example
This example starts a thread that does nothing but wait and kills it immediately:
int pid = Eval("Delay(50000);");
KillThread(pid);

161
RaiseError
RaiseError — Trigger an exception
Synopsis

Defined in
Built-in function

Function prototype

void RaiseError(int errno, str message);

Description
This function can be used to raise an exception in a Rembo-C script. The exception
will suspend the active thread and trigger a call to the current exception handler. If
no exception handler is defined (i.e. the Rembo-C statements are not surrounded
with a with() try block), then the function DefaultExceptionHandler is called.
The first parameter is the decimal number of the exception to trigger, and message
is an optional message that is passed to the exception handler (custom error
message).
Here is the list of exceptions defined in REMBO, with their numerical identifier:

• 1: "No such file or directory"


• 2: "Too many open files"
• 3: "Permission denied"
• 4: "Bad file number"
• 5: "Not enough core"
• 6: "Unknown error"
• 7: "No such device"
• 8: "Invalid argument"
• 9: "Not a directory"
• 10: "Is a directory"
• 11: "File too large"
• 12: "No space left on device"
• 13: "Illegal seek"

162
RaiseError
• 14: "Filesystem inconsistency detected"
• 15: "Read-only file system"
• 16: "Broken pipe/connection"
• 17: "File already exists"
• 18: "Operation not permitted"
• 19: "Input/output error"
• 20: "No such device or address"
• 21: "Resource temporarily unavailable"
• 22: "No more information available"
• 23: "Resource busy"
• 24: "Operation not supported"
• 25: "Syntax error"
• 26: "Aborted on user request"
• 28: "Incompatible VM version"
• 30: "String too long"
• 31: "Invalid number format"
• 32: "Invalid boolean value"
• 33: "Invalid date/time format"
• 34: "Invalid IP format"
• 38: "Improper use of variable"
• 39: "Global variable already exists"
• 40: "No such global variable"
• 41: "Not a numeric variable"
• 42: "Not a boolean variable"
• 43: "Not a textual variable"
• 44: "Not a function"
• 45: "Not an array"
• 46: "Not a labelled array"
• 47: "Not a binary buffer"
• 48: "Not a variable"
• 49: "Index out of range"

163
RaiseError
• 50: "Invalid variable name (too long)"
• 51: "Too many variables"
• 52: "Too many arguments"
• 53: "More arguments expected"
• 54: "Read-only variable"
• 55: "Type-protected variable"
• 56: "Variable is not comparable"
• 57: "Single character expected"
• 58: "No such key in variable"
• 59: "Bad cast"
• 60: "Connection reset by peer"
• 61: "Protocol error"
• 62: "Cannot assign requested address"
• 63: "Network is unreachable"
• 64: "No buffer space available"
• 65: "Transport endpoint is not connected"
• 66: "Host is down"
• 67: "No route to host"
• 68: "Timeout"
• 69: "Bad file format"
• 70: "Too many open windows"
• 71: "No such window"
• 72: "Invalid font file"
• 73: "No such font"
• 74: "Cannot boot on device"
• 75: "Faulty exception handler"
• 76: "User not logged in"
• 77: "Parsing error"
• 78: "File or record deleted"
• 79: "Too many open devices"
• 80: "File is not an archive"

164
RaiseError
• 81: "Archive inconsistency detected"
• 82: "Cannot merge archive"
• 83: "Bad compressed format"
• 84: "Net-based file expected"
• 85: "Inconsistency error detected in low-level cache"
• 86: "Connection refused"
• 89: "Division by zero"

Example
if (!FileExists(myfile))
RaiseError(1,"Could not find the specified file");

165
DefaultExceptionHandler
DefaultExceptionHandler — Default exception handler
Synopsis

Defined in
Built-in function

Function prototype

void DefaultExceptionHandler(var exc);

Description
This is the function called by the Virtual Machine when an exception is triggered,
but no exception handler is defined. The default implementation of this function is
to display an error message in the console log, and return.

Use the Rembo-C keywords with(...) try { } to implement structured


exception handling, rather than defining a new global exception handler.
Do not reimplement this function directly. If you want to setup your own global
exception handler, write your handler in a separate function, and then change the
value of the global variable ExceptionHandler to your exception handler. Since the
DefaultExceptionHandler will still be available, you will be able to call it at the
end of your exception handler to generate a default error message.
The variable exc passed in parameter to the exception handler contains the
following members:

• int errno: the numerical code of the exception;


• str msg: the standard error message associated with the exception numerical
code;
• str irritant: a custom message set by the function that triggered the
exception. Might be undefined (empty string);
• int thread: the identifier of the thread suspended by the exception;
• str srcfile: the filename containing the line that triggered the exception. If the
Rembo-C was not compiled, this member is filled with WinEval/Eval. The RBX
module must have been compiled with -g (debug infos).

166
DefaultExceptionHandler
• int srcline: the line number of the Rembo-C statement that triggered the
exception. The RBX module must have been compiled with -g (debug infos) in
order to get the line number at run-time.
• bool resume: this member is not used in the default exception handler. In other
exception handlers (used for a with () try {} clause), this member determines
whether the thread execution is terminated (value is false), or whether the thread
execution is resumed at the next instruction after the with () try {} clause
(value is true).

Example
var MyExceptionHandler(var exc)
{
// do custom error handling
// call the default handler
return DefaultExceptionHandler(exc);
}
// Set the new exception handler:
#pragma clear ExceptionHandler
ExceptionHandler = MyExceptionHandler;

167
LogVar
LogVar — Display any kind of variable on the console log window
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void LogVar(var object);

Description
LogVar displays the content of the variable given as parameter. It will automatically
detect the variable and display a suitable textual representation of the variable. For
example, using LogVar to display a bool variable will result in the text true or
false.

As LogVar displays the content of the variable on the console window, it is best
suitable for debugging purposes.

See also
See also Print to display immediate numbers and strings.

168
GlobalVars
GlobalVars — Retrieve an array of global variables matching a pattern
Synopsis

Defined in
Built-in function.

Function prototype

var GlobalVars(str pattern);

Description
This functions returns a structure containing all the global variables matching a
given pattern. The pattern has the same format as in the StrMatch function.
You can use this function to display all the global variables defined. Since functions
are stored as variable, you can also use this function to determine the exact name of
a function given the first characters of the name.

Tip:once you have the name of the function you are looking for, you can use
Log(functionname); to display the prototype (i.e. usage) of the function. Try
Log(CopyFile); for example.

Example
LogVar(GlobalVars("dhcp*"));
LogVar(StructKeys(GlobalVars("strto*")));

169
3.10. Persistent Variables

Export
Export — Make a variable persistent
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void Export(var variable, str varname, str scope);

Description
Export creates a persistent declaration for the given variable. That means that a
variable named varname with the contents of variable will be available in next
sessions (the variable content will not be lost with a reboot).
The scope parameter identifies the scope in which the variable must be created. It
can be one of these values:

• global: the variable is added to the global variable list. All computers will see
this variable on next boot.
• group: the variable is added to the group variable list. All computers within the
same group as this host will see this variable on next boot.
• host: the variable is added to the host’s private variable list. Only this host will
see the variable on next boot.
• user: the variable is added to the user’s private variable list. Only the logged in
user will see the variable on next boot when it is successfully authenticated.

If a declaration already exists for the given variable in the given scope, the previous
declaration is overwritten with the new one.
The UnExport function can be used to remove a variable declaration created with
Export.

170
Export
See also
See also Section 2.2.3 in REMBO Client Administration Manual for a discussion
about persistent variables.

171
UnExport
UnExport — Remove an export declaration
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void UnExport(str varname, str scope);

Description
UnExport removes a persistent declaration for the given variable name in the given
scope.
The scope parameter identifies the scope from which the variable must be
removed. UnExport does not affect variables exported with another scope, even if
the variable name matches.

See also
See also Section 2.2.3 in REMBO Client Administration Manual for a discussion
about persistent variables.

172
VarToExpr
VarToExpr — Answer a script expression for a given variable value
Synopsis

Defined in
Built-in function.

Function prototype

str VarToExpr(var any);

Description
This function is used internally by Export and UnExport to transform a variable in a
textual representation.
This function can convert all simple types and arrays of simple types. A variable of
type var can also be converted if it contains an expression of simple types or array
of simple types.

Example

int arrayInt[] = { 3, 55, -2 };


var P = arrayInt;
Print(VarToExpr(P)); // {"3","55","-2"}

str name = "tool";


P = {"RBO", 3, true, name};
Printf(VarToExpr(P)); // {"RBO","3","true","tool"}

173
3.11. Network-related primitives

NetFile
NetFile — Find a host-specific, group-specific or global file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str NetFile(str path);

Description
NetFile checks if the file path exists in the host specific network directory
(net://host/). If the file does exist, it returns with the complete path to the file:
net://host/path.

If the given path does not exist in the host specific directory, then the group specific
directory will be searched for this path. If the path exists, the function returns with
net://group/path. Else, NetFile tries to find the path in the global network
directory. If the file is found in the global directory, the function returns with
net://global/path. If the file cannot be found in either the host, group or global
directory, then the NetFile will raise a file not found error.
This function can be used to access configuration or profile information. NetFile
always return the most specific file, so that it is possible to override a global file
with more specific (group or host specific) file.

Example

To patch a disk file with a reference file located on the network, either in the host,
group or global directory, use
FilePatch(NetFile("reference"),"disk://0:1/destination");

174
NetFile
See also
See also Net URLs.

175
NetFullPath
NetFullPath — Retrieve the global network path for a given scope
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str NetFullPath(str url, str scope);

Description
This function builds the global path of an Net-URL scope. For example, the path
net://group corresponds to the path net://global/groups/Default if the host
you are running REMBO on is a member of the group "Default".
The parameter url can be either "net" or "cache".
The parameter scope can be either

• "global": the result will be url+"/global";


• "group": the result will be url+"/global/groups/"+HostInfo.GroupName;
• "host": the result will be url+"/global/hosts/"+HostInfo.HostID;
• "user": the result will be url+"/global/users/"+AuthInfo.UserName (an
exception is raised if no user is logged on);

176
CachedFileStat
CachedFileStat — Retrieve the status of a file stored in the cache partition
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var CachedFileStat(str path);

Description
This function returns the cache status of a network file (i.e. whether the file exists in
the cache partition or not).
The parameter path must be a valid net: or cache: path.
The returned variable is an enumeration of the following strings:

• "error": the given file does not exist or is not a valid network file;
• "remote": the given file is not present in the local cache partition;
• "outdated": the given file has a copy in the local cache partition, but this copy is
not up to date with the original file on the server (i.e. the file will be downloaded
on next open);
• "cached": the given file has a valid copy in the local cache partition;

Example
if (CachedFileStat("cache://global/rembo.shtml")!="cached")
Log("The rembo.shtml file is not cached<br>");

177
RemoveCachedFile
RemoveCachedFile — Remove a file from the cache partition
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var RemoveCachedFile(str path);

Description
This function purges the cached copy of the given network file from the local cache
partition.
The parameter path must be a valid net: or cache: path.
RemoveCachedFile returns without error if the given file has no cached copy in the
local cache partition.

Example
// Make some room in the cache
RemoveCachedFile("cache://global/mydiskimage");

178
SysLog
SysLog — Send a message to the server log
Synopsis

Defined in
Built-in function.

Function prototype

void SysLog(str msg);

Description
This function sends a request to the REMBO server to write a message in the log
file for this host. The message will be written in a file called XXXXXXXXXXXX.log
(XXXXXXXXXXXX is the hardware address of the client host). The host-specific log
files can be found in the logs sub-directory of the server installation directory.

Example
if (!FileExists("disk://0:1"))
SysLog("The master partition is corrupted!");

179
SysLogF
SysLogF — Send a message to a custom server log
Synopsis

Defined in
Built-in function.

Function prototype

void SysLogF(str logfile, str msg);

Description
This function sends a request to the REMBO server to write a message in a custom
log file. The message will be written in the file specified by logfile (relative
path). This custom log file, like other server log files, is stored in the sub-folder
logs in the server installation directory. Custom log files are not available through
REMBO filesystem, but can be viewed with a text editor on the server.
SysLogF is a generic form of the SysLog. Calling SysLog("msg"); is equivalent to
SysLogf(NetInfo.HostID+".log","msg");.

Example
SysLogF("bootcount.log","Host "+NetInfo.HostID+" is ready.");

180
DownloadFile
DownloadFile — Download a file in multicast without using the hard-disk
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var DownloadFile(str remotefile);

Description
This function should be used to download a remote file using an efficient multicast
protocol, but without using the local cache partition (multicast to memory). The
function returns the loaded object into a binary block, as LoadBinaryFile (or
LoadFile) would have done.

The parameter remotefile must point to a net: path.


The default implementation for this function is to use the MCAST protocol
(InitDownload+MoreDownload functions) if the variable Settings.UseMCAST is set
to true, and to use an unicast protocol if the variable is set to false.
If the MCAST protocol is used, the file will be transferred from the server to the
local file with a multicast protocol. If you want to limit the bandwidth used by the
multicast protocol to spare your network resources, you can modify the
Settings.MCASTSpeed variable. The higher this variable is, the slower the transfer
will be.

Example
The following program downloads a raw floppy disk image into a ramdisk using
multicast, without using the cache partition (works on a diskless computer):
var ramdisk = DownloadFile("net://global/floppy.ima");
CreateRamDisk(0,sizeof(ramdisk));
SaveFile(ramdisk,"ram://0:RAWFS/RawPartition01");
RDBoot(0);

181
Download
Download — Download a file from the server with the MCAST protocol
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void Download(str remotefile, str localfile, bool md5);

Description
This function is called by the cache: URL handler to copy server files to the local
cache partition. You can use this function to initiate file transfers between the server
and any local file (and using the MCAST protocol if the system is configured for
multicast transfers).
The parameter remotefile must point to a net: path.
The parameter md5 is used by the cache: URL handler to retrieve the MD5 sub-file
instead of the real file.
The default implementation for this function is to use the MCAST protocol
(InitDownload+MoreDownload functions) if the variable Settings.UseMCAST is set
to true, and to use an unicast protocol if the variable is set to false.
If the MCAST protocol is used, the file will be transferred from the server to the
local file with a multicast protocol. If you want to limit the bandwidth used by the
multicast protocol to spare your network resources, you can modify the
Settings.MCASTSpeed variable. The higher this variable is, the slower the transfer
will be.
It is not recommended to reimplement this function with your own function unless
you have carefully studied the default implementation in utils.rbc (available with
the SDK).

Example
Download("net://global/myimage","disk://0:1/storage",false);

182
FileDownloadInProgress
FileDownloadInProgress — Answer true iff there is an ongoing MCAST
download for a specified file
Synopsis

Defined in
Built-in function.

Function prototype

bool FileDownloadInProgress(str serverfile);

Description
This function allows a client the control whether or not there is an ongoing MCAST
transfer on a file. The information is taken from the server. If there is was an
ongoing transfer but the last client has timed-out, the function will answer false as
if the transfer was closed normally.
The parameter serverfile must point to a cache: path.

See also
See MetaCast for a more elaborate way to synchronize multicast downloads.

183
MetaCast
MetaCast — Run a MetaCast synchronized transfer (deprecated)
Synopsis

Defined in
/plugins/metacast.rbx (deprecated)

Function prototype

int MetaCast(str BatchID, var FileList, int MinClients, int


StartTimeout);

Description
This function initiates a MetaCast synchronized transfer. Use this function to start a
multicast transfer on multiple clients to send multiple files using the MCAST
protocol, but with an additional level of synchronization.

The BatchTransfer function, introduced in release 2.0 of REMBO does a


similar job but using a more efficient synchronization protocol. In addition,
BatchTransfer also handle the synchronized download of shared files used by
the new archive format. Consequently, the use of MetaCast is not any more
recommended.
The first parameter, BatchId, is the name of the MetaCast session. All clients
sharing the same name will be synchronized. It is not recommended to have
multiple MetaCast sessions at the same time on the same network, as MetaCast was
developped to avoid this situation.
The second parameter is array of strings. Each string element is the name of a file to
transfer using MetaCast. Files may be transferred in a different order as the order
used in this array, because MetaCast reorders files based on the size of each file to
make sure bigger files are sent last, when most clients have joined the session. Not
all clients in the same session need to have the same list of files to transfer. If one
client requests a download for a file that was not specified in the files array for
another client, the client that does not need the file will skip the download request
and wait for the next file. It is however recommended to have very similar files list
on all clients participating to the same MetaCast session to improve the total
transfer time (all clients wait until all files are transferred).
Parameters MinClients and StartTimeout are the number of clients needed
for a MetaCast transfer to start, and the global time (in seconds) to wait until the

184
MetaCast
MetaCast transfer start, respectively. Both conditions must be true for the MetaCast
transfer to start. For example, if MinClients is 5, and StartTimeout is 120,
the MetaCast transfer will start two minutes after the first client has joined the
MetaCast session, but only if there are at least five clients in the MetaCast session.
If less than five clients are active, they will wait until a fifth client join to start the
transfer, even if the two minutes time is elapsed. As a special case, if both
parameters are zero, the transfer will be done immediately and without any
synchronization mechanism outside the MCAST protocol itself.
When a MetaCast session is terminated, the MetaCast returns with the number of
clients that have participated to the session, or -1 if an error occurred during the
transfer. An error could be a transfer error on a single file, and does not mean that
all files have failed.
MetaCast synchronization state is stored on the server, using a server lock. If the
server is restarted, the synchronization will automatically be rebuilt, but this may
cause some desynchronization between hosts. Inversely, if a client is turned off
within a transfer, the other clients will wait some time and then consider the client
as dead some time after the server multicast session has timed out. The transfer will
therefore resume normally.

Example
var files = { "cache://global/file1",
"cache://global/file2",
"cache://global/file3" };

MetaCast("TestMC",files,5,120);

See also
See also BatchTransfer and CopyCache.

185
BatchTransfer
BatchTransfer — Run a multiple file transfer
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void BatchTransfer(var files, str synchroParams);

Description
This function initiates a batch transfer of multiple files, possibly including archives
bound to files stored in the shared file repository. The transfer typically occurs
between the server and a set of clients, using the PCAST multicast protocol, as
described in Section 2.5.3 in REMBO Client Administration Manual. However, the
function can also be used to copy multiple files from one local device to an other, or
to upload a set of files to the server. The function automatically displays a progress
bar showing the global progress of the transfer.
The first parameter files is a two-dimensional array, each row describing one file
to be copied. The first item of the row is the source file path, the second item is the
destination file path, and the last item is a numeric bitfield specifying whether the
file itself should be transfered (bit with value 1), the MD5-subfile should be
transfered (bit with value 2) and the shared files required by the archive should be
transfered (bit with value 4). In doubt, use the value 7 to transfer all components
related to the file.
If the transfer is not a multicast download (e.g., the source is not the server or the
global variable Settings.UseMCAST is false), the parameter synchroParams should
be left empty. Otherwise, it can be used to specify how the multicast clients should
be synchronized, and should be of the form "ID:clients:timeout". The ID
identifies the transfer and should be the same amoung a group of clients to
synchronize. The expected number of clients to wait for is specified by clients,
and the timeout to wait before considering that a client is dead or missing is given
by timeout. The default synchronization parameters are "Multicast:1:5", which
means that the transfer will start as soon as one client is ready (even if other clients
may still join later), and every connected client will ever be expected to be
responsive within 5 seconds after a request is sent.

186
BatchTransfer
Example
// Download two files (and related shared files) using
// multicast synchronization with 20 computers, but
// start transfer after no more than 10 seconds
BatchTransfer(
{{"net://global/arch.img","disk://0:-1/arch.img",5},
{"net://global/wiz.rbx", "disk://0:-1/wiz.rbx", 1}},
"Test:20:10");

See also
See also CopyCache.

187
CopyCache
CopyCache — Preload a cache partition
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

int CopyCache(var fileList, str destPath, bool unconditional, str


synchroParams);

Description
Similarly to BatchTransfer, this function initiates a batch transfer of multiple files,
possibly including archives bound to files stored in the shared file repository.
However, CopyCache provides a more convenient front-end when the purpose of the
transfer is to preload a Rembo cache partition, where the files are stored by inode
number rather than by filename. In addition, this function can automatically check
whether there is already an up-to-date file in the cache partition.
The fileList parameter is a simple array of source file names. The destination
directory where the cache structure should be created is given by destPath, and
is typically set to Settings.CachePath. If you only want to copy the files that are
not yet present in the cache partition or that are outdated, set the unconditional
parameter to false.
If the transfer is not a multicast download (e.g., the source is not the server or the
global variable Settings.UseMCAST is false), the parameter synchroParams should
be left empty. Otherwise, it can be used to specify how the multicast clients should
be synchronized, and should be of the form "ID:clients:timeout". The ID
identifies the transfer and should be the same amoung a group of clients to
synchronize. The expected number of clients to wait for is specified by clients,
and the timeout to wait before considering that a client is dead or missing is given
by timeout. The default synchronization parameters are "Multicast:1:5", which
means that the transfer will start as soon as one client is ready (even if other clients
may still join later), and every connected client will ever be expected to be
responsive within 5 seconds after a request is sent.

188
CopyCache
Example
To ensure that an archive and all related shared files are present in the cache
partition, you can simply use the following code:
CopyCache({"cache://global/test.img"},
Settings.CachePath,false,"");

189
GetLock
GetLock — Acquire a named lock on the server for synchronization
Synopsis

Defined in
Built-in function.

Function prototype

bool GetLock(str lockname);

Description
This function sends a request to the REMBO server to acquire an exclusive access
to the lock with the name specified by lockname. If no such lock exists, a new
lock is created and automatically acquired.
The return value is true if the lock has been acquired for exclusive access, or false
if the lock is already acquired by another host. If GetLock is used in a loop to retry
until the lock is acquired, a delay should be added between each retry or the server
will be saturated by GetLock (use the delay()).
GetLock is very useful for making sure that only one host access a networked
resources at a given time. This function should always be used when several hosts
write in the same file, because only one host can have write access on a network file
at a time.
Use ReleaseLock to release a lock previously acquired. You cannot release a lock
acquired by another computer, or a lock not acquired at all.
If the name of the lock begins with ’@’, a variable with the same name as the lock
(without the ’@’ character) will be used to store a numerical value associated with
the specified lock. The value of the newly created (or modified) variable will be set
to the value of the lock as stored on the server. If no value was associated with the
lock, the variable is set to 0. Use ReleaseLock to release such a lock and to modify
the value associated with the lock on the server. Note that the lock value is volatile
on the server-side: if the server is restarted, the value is reset to 0.
If the name of the lock begins with ’$’, a variable with the same name as the lock,
but without the ’$’ character will be used to store a textual (string) value associated
with the specified lock. As with numerical locks (see above paragraph), textual
locks are modified/released with ReleaseLock.

190
GetLock
Example
/* Append some text to a global file */
while (!GetLock("logfile")) {
delay(100); // wait 1 sec between retries
}
/* lock is acquired, append to file */
var f = FileOpen("net://global/logfile","a");
FileWrite(f,BinFromStr(msg),0,sizeof(msg));
FileClose(f);
/* release lock */
ReleaseLock("logfile");

// numerical lock
int mylock;
GetLock("@mylock");
Printf("Value of mylock on the server is %d<br>",mylock);
mylock++;
ReleaseLock("@mylock");

// textual lock
str strlock;
GetLock("$strlock");
Printf("Value of strlock on the server is %s<br>",strlock);
strlock = "new test";
ReleaseLock("$strlock");

191
ReleaseLock
ReleaseLock — Release a named lock on the server
Synopsis

Defined in
Built-in function.

Function prototype

bool ReleaseLock(str lockname);

Description
This function release a server lock previously acquired with GetLock. The lock
name specified by lockname must be the same as specified in the call to GetLock.
ReleaseLock returns false if the lock could not be released, or true if the lock has
been successfully released.
If the acquired lock was a numerical or textual lock, the value of the local variable
is sent to the server to be associated with the lock for further references through
GetLock.

See also
See GetLock for a discussion about locks.

Example
/* Append some text to a global file */
while (!GetLock("logfile")) {
delay(100); // wait 1 sec between retries
}
/* lock is acquired, append to file */
var f = FileOpen("net://global/logfile","a");
FileWrite(f,BinFromStr(msg),0,sizeof(msg));
FileClose(f);
/* release lock */
ReleaseLock("logfile");

// numerical lock
int mylock;
GetLock("@mylock");
Printf("Value of mylock on the server is %d<br>",mylock);
mylock++;

192
ReleaseLock
ReleaseLock("@mylock");

// textual lock
str strlock;
GetLock("$strlock");
Printf("Value of strlock on the server is %s<br>",strlock);
strlock = "new test";
ReleaseLock("$strlock");

193
WakeRemoteHost
WakeRemoteHost — Wake up hosts remotely (Wake on Lan)
Synopsis

Defined in
Built-in function.

Function prototype

void WakeRemoteHost(var macaddr);

Description
This function asks the Rembo server to send a wake-up packet (wake-on-lan) to a
client specified by its MAC address, specified by a binary object.
Be advised that wake-on-lan may not always work, depending on the way the
computer has been powered off and on whether it has been enabled or not in the
computer BIOS.

Example
WakeRemoteHost(BinFromHex("000102030405"));

194
3.12. System primitives

Interact
Interact — Bring an interactive evaluator window
Synopsis

Defined in
/plugins/admin.rbx

Function prototype

void Interact(void);

Description
Interact opens an interactive evaluator window. The interactive evaluator will
accept any kind of valid Rembo-C statement and execute it. You can use Interact
to test new functions or to debug your scripts.

195
ShowConsole
ShowConsole — Show the console log window
Synopsis

Defined in
Built-in function.

Function prototype

void ShowConsole(void);

Description
ShowConsole brings the console log window in front of any other window.
The console log window contains all error messages issued when REMBO fails
with one of its operation. Always check the console log when you install a new
script, to ensure that everything is working as expected.

196
HideConsole
HideConsole — Hide the console log window
Synopsis

Defined in
Built-in function.

Function prototype

void HideConsole(void);

Description
HideConsole hides the console log window, without destroying its content.
The console log window contains all error messages issued when REMBO fails
with one of its operation. Always check the console log when you install a new
script, to ensure that everything is working as expected.

197
Print
Print — Display text on the console window
Synopsis

Defined in
Built-in function.

Function prototype

void Print(...);
void Log(str text);

Description
Use Print to display a message on the console window. This function is useful for
debugging purposes. End your message with \n if you want to output a carrier
return.
If you call Log (or Print) with a variable or a function as an argument, the variable
will be first converted to a string and then displayed. You can use this behaviour to
display the usage syntax of any Rembo-C function because the string representation
of a function is its prototype (i.e. the number of arguments and the name of
arguments). Note that this will not work on internal functions, which are not stored
in Rembo-C variables.

See also
See also LogVar to display complex data types.

198
Printf
Printf — Format text on the console window
Synopsis

Defined in
Built-in function.

Function prototype

void Printf(str format, ...);

Description
This function is analoguous to Print in that it displays a message in the console
window. The difference is that this function uses a format string to format the given
variables, just like Strf does.
See the manual page of Strf for more information about the format string.

Example
Printf("%-20x\t%s is [%s]<br>br",number,name,value);

199
FatalError
FatalError — Trigger a fatal error, stop REMBO
Synopsis

Defined in
Built-in function.

Function prototype

void FatalError(str msg);

Description
This function needs to be used carefully. It will call the fatal error handler of
REMBO to stop all activity immediately and display the given message.
When a fatal error occurs (or when this function is called), the following actions are
performed:

• All threads are suspended;


• The display is reset to text mode;
• The fatal error message is displayed in the upper-left corner of the screen;
• If the variable Settings.AutoBoot is set to true, the computer is rebooted after
10 seconds. Otherwise the computer is locked;

The AutoBoot setting can be modified in the group configuration on the server.
See the server reference manual for more information.

200
GarbageCollect
GarbageCollect — Force memory garbage collection
Synopsis

Defined in
Built-in function.

Function prototype

void GarbageCollect(void);

Description
This function forces a garbage collect of all unused Rembo-C variables. Garbage
collecting occurs automatically. You should not need to start this command in a
script.

201
FlushAll
FlushAll — Commit to disk all cached data
Synopsis

Defined in
FlushAll: /plugins/utils.rbx

Flush: Built-in function.

Function prototype

void FlushAll(void);

Description
FlushAll commits all cached structures to the disk, so that the computer can be
powered down safely at any time.
The high performance of REMBO for disk access is partly due to its sophisticated
cache system. However, the drawback of using a write-behind cache is that if the
computer is unexpectedly powered off, some data may have not yet been committed
to the disk. For this reason, it is wise to call FlushAll in your scripts between
disk-intensive operations and user interactions.
FlushAll is an alias for Flush.

202
Keyb
Keyb — Change the keyboard mapping
Synopsis

Defined in
Keyb: Built-in function.
LoadKeyMap: Built-in function.

Function prototype

void Keyb(str country);


void LoadKeyMap(str keymappath);

Description
Keyb loads a keyboard mapping from the server. The parameter country is the
usual abbreviation for keyboard mappings. Standard keymaps are

• us - United States (default)


• uk - United Kingdom
• de - Germany
• fr - France
• it - Italy
• es - Spain
• pt - Portugal
• be - Belgium
• no - Norway
• se - Sweden
• fi - Finland
• sf - Swiss (French)
• sg - Swiss (German)
• cf - Canada (French)

203
Keyb
Additional keymaps can be defined using the keymap program, available in the
Rembo SDK.
Keyb(str country) is equivalent to
LoadKeyMap("net://global/keymaps/"+country+".map");.

Example

The following example loads a UK english keyboard mapping:


Keyb("uk");

204
CodePage
CodePage — Change the active codepage
Synopsis

Defined in
Built-in function.

Function prototype

void CodePage(int pageid);


void LoadCodePage(str cpfilepath);

Description
CodePage loads a codepage mapping from the server. The code page ID can be any
of the following:

• 437 - IBM PC-8 (default)


• 737 - IBM Greek
• 850 - IBM Latin I (US, Western Europe, Australia)
• 852 - IBM Latin II (Eastern Europe)
• 855 - IBM Cyrillic (Russian)
• 857 - IBM Turkish
• 860 - IBM Portuguese
• 861 - IBM Icelandic
• 862 - IBM Hebrew
• 863 - IBM Canadian-French
• 864 - IBM Arabic
• 865 - IBM Nordic
• 866 - IBM Russian
• 869 - IBM Modern Greek
• 874 - Windows Thai
• 932 - Windows Japanese
• 936 - Windows Simplified Chinese

205
CodePage
• 949 - Windows Korean
• 950 - Windows Traditional Chinese
• 1250 - Windows Latin II
• 1251 - Windows Cyrillic
• 1252 - Windows Latin I
• 1253 - Windows Greek
• 1254 - Windows Turkish
• 1255 - Windows Hebrew
• 1256 - Windows Arabic
• 1257 - Windows Baltic
• 1258 - Windows Korean

Internally, Rembo uses Unicode strings and is therefore not sensitive to code pages.
However, code pages have to be used for two reasons:

• For building short names for FAT and NTFS partitions;


• For converting Unicode strings to and from their 8-bits representation when
accessing 8-bits text files.

If you are working with Windows in English, or if you are using Linux only, you
probably do not need to load a code page. In most other cases, it is very
important to load the appropriate code page before restoring a disk image to
the disk, since the encoding of filenames differs depending on the code page
used by Windows. Forgetting to load a code page can result in incorrect
directory entries.
For historical reasons, many code pages are redundant. The most obvious
redundancy is between the 800 code-page family and the 1200 code-page family.
The former has been introduced by IBM long time ago, and the latter is a
cleaned-up and simplified version used in Windows. However, in many cases,
Windows still uses the old encoding internally, and in particular for the short
filenames. Therefore, if you are unsure of the code page you have to use, try with
one from the 800 family first.
Note that the code page is not used for reading a partition (Rembo reads the
Unicode long names), so even if you have not set the appropriate code page at the
time you created your disk image, the image should be correct.

206
CodePage
If you are using REMBO wizards, you can change the active codepage with the
Computer Settings button.

Note: CodePage() is a wrapper to the internal function LoadCodePage(). The


CodePage() automatically build the correct path for LoadCodePage(). If you want
to use LoadCodePage() directly, you will probably need to know that all default
codepages are stored in net://global/codepages.

If you are using REMBO to backup and restore far-east version of Windows
95/98, you must set the proper active codepage for the Windows version you
are using. Note that Windows NT/2000 is not concerned by codepages.

Example

The following example loads a Latin-I code page, for restoring a disk image of
Microsoft Windows, french edition:
CodePage(850);

207
Time
Time — Retrieve the current value of the internal time counter
Synopsis

Defined in
Built-in function.

Function prototype

int Time(void);

Description
This function returns the current value of the internal time counter. The internal
time counter is a monotone 100Hz counter. It is incremented automatically every
100th of seconds (i.e. 100 counts = 1 second).
The counter is stored in a 32bits value. This means that the counter will wrap back
to zero after approximatively 500 days of continuous use. The counter is set to zero
when REMBO starts.
You can use this counter to get precise timing measures. Here is an example in
Rembo-C:
int start = Time();
// do an operation
int stop = Time();
int delta = stop-start;
Printf("Time spent in the operation: %d ticks<br>",delta);
Printf("Time in seconds: %d.%d<br>",delta/100,delta%100);

208
GetMemoryInfo
GetMemoryInfo — Retrieve information about the system memory usage
Synopsis

Defined in
Built-in function.

Function prototype

var GetMemoryInfo(void);

Description
This function retrieves information about the current state of the memory. It returns
a structure containing three members:

• int total: the total amount of memory in bytes;


• int free: the number of free bytes;
• int nhandles: the count of handles used (only for debugging purposes);

Example
var mi = GetMemoryInfo();
str msg = "<table>";
msg+="<tr><td>Total memory: <td>"+SizeToStr(mi.total));
msg+="<tr><td>Free memory: <td>"+SizeToStr(mi.free));
msg+="<tr><td>Handles used: <td>"+SizeToStr(mi.nhandles));
msg+="</table>";
OpenNotice("meminfo",msg);

209
GetNetStats
GetNetStats — Retrieve statistics from the network interface
Synopsis

Defined in
Built-in function.

Function prototype

var GetNetStats(void);

Description
This function retrieves statistics on the current usage of the network interface. These
statistics can be used to display information about the current usage of the network.
The structure returned by GetNetStats contains the following members:

• int rcvcount: number of frames received by REMBO;


• int xmtcount: number of frames sent by REMBO;
• int xmtbusy: number of frames for which the PXE bootrom returned a ’busy’
error code on transmit;
• int dropcount: number of frames dropped by REMBO on receive because the
input buffers were full;
• int drvxmt: number of frames sent at the PXE bootrom level;
• int drvrcv: number of frames received at the PXE bootrom level;
• int crcerrors: number of frames containing a checksum error detected by the
PXE bootrom;
• int qerrors: number of frames dropped by the PXE bootrom because the input
buffer of the network card was full;

Example
var ni = GetNetStats();
Log((str)ni.rcvcount+" received frames, and "
(str)ni.xmtcount+" sent frames<br>");

210
GetNetStats

211
GeneratePassword
GeneratePassword — Generate a random password
Synopsis

Defined in
Built-in function.

Function prototype

str GeneratePassword(int length);

Description
This function generates a random string that can be used as a password. The
generated string will be built to contain exactly length characters.
This function uses BinSetRandom to generate random data.

212
FileTest
FileTest — Perform a full read test on a device
Synopsis

Defined in
Built-in function.

Function prototype

void FileTest(str path);

Description
This function performs a full read test in the path specified by path. All files and
directories will be read by REMBO to ensure that the filesystem is not corrupted.
Use this variable if you suspect that the filesystem is corrupted, and you want to
know which file is corrupted. FileTest will stop on the first corrupted file.

Examples
FileTest("disk://0:1"); // test partition 1
FileTest("disk://0:1/winnt"); // test a specific directory

213
LogDir
LogDir — Dump the content of a directory to the console log
Synopsis

Defined in
/plugins/admin.rbx

Function prototype

void LogDir(str path);

Description
This function reads the content of a directory and dumps that content in the console
log window. This command is faster than opening a File Manager, but it is less
verbose and not graphically oriented.
This function does not recursively process sub directories.

Examples
Examples of common usage:
LogDir("disk://0:1/winnt");
LogDir("link://linux/usr");
OpenArchive("myimage","cache://global/myimage");
LogDir("arch://myimage");
CloseArchive("myimage");

214
ViewDir
ViewDir — Open a directory browser dialog
Synopsis

Defined in
/plugins/admin.rbx

Function prototype

void ViewDir(str path);

Description
This function reads the content of a directory and shows the result in a window.
Elements displayed in the window are clickable. If the user clicks on a directory, the
content of the window will be replaced by the content of that directory. If the user
clicks on a file, a TextEdit window is opened for the file.
ViewDir is an intermediate tool between LogDir and FileMan. It is faster than the
File Manager, but less user-friendly.

Examples
Examples of common usage:
ViewDir("disk://0:1/winnt");
ViewDir("link://linux/usr");
OpenArchive("myimage","cache://global/myimage");
ViewDir("arch://myimage");
CloseArchive("myimage");

215
CMOSRead
CMOSRead — Read data from the CMOS memory
Synopsis

Defined in
built-in function

Function prototype

var CMOSRead(int register, int len);

Description
This function reads data from the CMOS memory. The CMOS memory is a special
non-volatile area used by the BIOS to store configuration information. The actual
layout of the information is specific to the BIOS vendor.
len CMOS registers (bytes) are read starting at register register. The data is
returned as a binary buffer of length len.

Example
var bin = CMOSRead(0x10,2);
Log(BinToHex(bin));

216
CMOSWrite
CMOSWrite — Write data to the CMOS memory
Synopsis

Defined in
built-in function

Function prototype

void CMOSWrite(int register, int len, var buffer);

Description
This function writes data from the CMOS memory. The CMOS memory is a special
non-volatile area used by the BIOS to store configuration information. The actual
layout of the information is specific to the BIOS vendor.
len CMOS registers (bytes) are written starting at register register. The data is
fetched from the binary buffer bin of length len (bytes).

Example
// Clear register 0x10
var bin = CMOSRead(0x10,1);
BinFill(bin,0,1,0);
CMOSWrite(0x10,1,bin);

217
Chapter 4. Basic Management Operations

This chapter describes the basic operations available in REMBO to perform simple
pre-OS management tasks. They are available in all versions of REMBO.

4.1. Basic management operations by category


Table 4-1. FDTitle;

BuildFloppyImage Save the image of a floppy disk to a raw


file
RestoreFloppyImage Restore a raw floppy image to a floppy
disk
CreateRamDisk Allocate a ramdisk
LoadRamDisk Load a raw floppy-disk image into a
ramdisk
RDClean Format a ramdisk
RDLoad Load a compressed image into a
ramdisk
FreeRamDisk Deallocate a ramdisk
CreateRemboFloppy Create a bootable floppy image of
Rembo

Table 4-2. Hard-disk setup operations

DeviceCount Answer the number of connected


devices
GetPrimaryPartitions Retrieve the list of primary partitions
GetPrimaryPartitionsEx Retrieves the list of primary partitions,
with more details
GetLogicalPartitions Retrieve the list of logical partitions
GetLogicalPartitionsEx Returns a detailed description of logical
partitions
FindExtendedPartition Retrieve the index of the extended
partition
ParsePartitions Build an array from a list of partitions
DescribePartitions Build a list of partitions from an array
FitPartitions Expand wildcards in a list of partitions
GetBootablePartition Retrieve the list of primary partitions
SetPrimaryPartitions Define primary partitions
SetPrimaryPartitionsEx Define primary partitions, with details

218
Chapter 4. Basic Management Operations

SetLogicalPartitions Define logical partitions


SetLogicalPartitionsEx Define logical partitions, with details
SetBootablePartition Define the bootable partition
SetOfflineMode Setup the hard-disk to boot Rembo by
default
HDClean Quick-format a partition
HDCheck Detect and fix corruptions in a
filesystem
BuildDiskImage Build a compressed image of a disk
partition
RestoreDiskImage Restore a disk partition from a
compressed image
CreateRemboCDRom Create a bootable ISO CD-Rom image
of Rembo

Table 4-3. Protected partitions handling

ClearProtectedPartitions Remove all protected partitions by


removing the BEER sector
GetProtectedPartitions Retrieve the list of protected partitions
SetProtectedPartitions Define protected partitions
GetBEER Retrieve the protected partitions global
parameters
SetBEER Update the protected partitions global
parameters
GetBEEREntry Retrieve the parameters of a given
protected partition
SetBEEREntry Update the parameters of a given
protected partition
HideProtectedPartitions Hide protected partitions by reducing
the disk size
UnhideProtectedPartitions Unhide protected partitions by restoring
the disk size
WriteRemboProtectedMBR Write a MBR that can boot into a
protected partition

Table 4-4. Booting functions

HDBoot Boot the computer on the specified


partition

219
Chapter 4. Basic Management Operations

RDBoot (RamDiskBoot) Let the computer boot on the ramdisk as


if it was a floppy
LXBoot (LinuxBoot, LinuxBootEx) Launch a Linux kernel
FloppyBoot Let the computer boot on a floppy disk
Reboot Reboot the computer
PowerOff Turn off the computer
BIOSBoot Resume the BIOS boot process

Table 4-5. GUI functions

MessageBox Display a message and wait for user


feedback
Logon Let the user logon to an authentication
server
FileChooser Open a file chooser dialog
OpenProgressBar Open a progress bar dialog
SetProgressBar Update the progress indicator in a
progress dialog
SetProgressInfo Update the informative text in a progress
dialog
CloseProgressBar Close progress dialog
OpenMessage Open a generic message dialog
OpenNotice Open a notice dialog
OpenYesNo Open a question dialog (yes/no dialog)
OpenMenu Open a graphical menu dialog
OpenEval Open a Rembo-C evaluation dialog
BuildFileSelect Build an HTML panel for choosing a
file

Table 4-6. Applicative functions

FDisk Open a partition table editor window


FileMan Open a file manager window
TextEdit Open a text editor window
OpenHTML Open an HTML browser window

Table 4-7. User console control

AddToRootMenu Add an entry to the root menu


LockKeyboard Disable the local keyboard
LockMouse Disable the local mouse

220
LockScreen Disable the local monitor
AddRemoteConsole (RConsole) Allow the connection of a remote
console
KillRemoteConsole Disconnect a remote console

4.2. Floppy-disk and ram-disk operations

BuildFloppyImage
BuildFloppyImage — Save the image of a floppy disk to a raw file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void BuildFloppyImage(str imagepath);

Description
BuildFloppyImage reads the full content of a floppy disk and makes a raw binary
image file with this content. The imagepath specifies the file in which the floppy
image shall be stored.
Floppy images can be used as ramdisks (LoadRamDisk), or can be restored to
another floppy (RestoreFloppyImage).

Example
BuildFloppyImage("cache://global/dosboot");
LoadRamDisk(0,"cache://global/dosboot");
RDBoot(0);

221
RestoreFloppyImage
RestoreFloppyImage — Restore a raw floppy image to a floppy disk
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void RestoreFloppyImage(str imagepath);

Description
RestoreFloppyImage writes the content of a raw floppy disk image to the current
floppy.
The floppy image specified by imagepath should have been created with
BuildFloppyImage or with a raw imaging utility (such as dd on Unix).

Example
RestoreFloppyImage("cache://global/dosboot");

222
CreateRamDisk
CreateRamDisk — Allocate a ramdisk
Synopsis

Defined in
Built-in function.

Function prototype

void CreateRamDisk(int ramdiskno, int bytesize);

Description
CreateRamDisk allocates a memory-based storage device (ramdisk) of the specified
size. Before using the ramdisk, you must format it using RDClean.
You should deallocate the ramdisk when you do not need it any more, using the
function FreeRamDisk.
As you can use several ramdisks at a time, use ramdiskno to specify the number
of the device you want to create (starting with 0).
If you want to load a floppy image in a ramdisk, use LoadRamDisk or RDLoad instead
of CreateRamDisk.
Ramdisks can be access with filenames starting with ram://x/ where x is the index
of the ramdisk (used in CreateRamDisk or LoadRamDisk).

The size of the ramdisk is only limited by the available free extended memory.

See also
See also RDLoad, RDLoad and FreeRamDisk.

223
LoadRamDisk
LoadRamDisk — Load a raw floppy-disk image into a ramdisk
Synopsis

Defined in
Built-in function.

Function prototype

void LoadRamDisk(str path);

Description
LoadRamDisk loads the raw floppy disk image given by path and creates a new
ramdisk of the appropriate size with it. If the floppy disk from which the image was
made was bootable, the ramdisk is likely to be bootable too (see the RDBoot
function).

LoadRamDisk creates a new ramdisk at the given ramdisk index. You do not
have to call CreateRamDisk first.
As you can use several ramdisks at a time, use ramdiskno to specify the index of
the device you want to create (starting with 0).
Ramdisks can be access with filenames starting with ram://x/ where x is the the
index of the ramdisk (used in CreateRamDisk or LoadRamDisk).

Example
LoadRamDisk(0,"cache://global/dosboot");
FileMan("ram://0");

See also
See also RDLoad.

224
RDClean
RDClean — Format a ramdisk
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void RDClean(int ramdiskno, str fstype);

Description
RDClean creates a new filesystem structure on the given Ramdisk (aka
Quick-Format). The parameter fstype specifies the kind of filesystem to install on
the partition, using the same keywords as for Ramdisk URLs.
A ramdisk formatted with RDClean will not be bootable unless you copy the
bootstrap files of your preferred OS on it.

Example
CreateRamDisk(0,500000); // 500kb ramdisk
RDClean(0,"FATFS"); // FAT filesystem
RDClean(0,"EXT2FS"); // Linux filesystem

225
RDLoad
RDLoad — Load a compressed image into a ramdisk
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void RDLoad(int devNum, int byteSize, str imageName);

Description
RDLoad creates a new ramdisk of the specified size, formats it according to the
format of the image given by imageName and restores the content of the image
into the ramdisk. If the image was made from a bootable floppy disk or partition,
the ramdisk is likely to be bootable too (see the RDBoot function).
Although ramdisks are usually created from a floppy disk, bootable FAT12
partitions can be used as well to create larger ramdisks.
As you can use several ramdisks at a time, use ramdiskno to specify the index of
the device you want to create (starting with 0).
Ramdisks can be access with filenames starting with ram://x/ where x is the the
index of the ramdisk.

Example
RDLoad(0,2048000, "cache://global/dosboot.img");
FileMan("ram://0");

See also
See also LoadRamDisk, RDBoot

226
FreeRamDisk
FreeRamDisk — Deallocate a ramdisk
Synopsis

Defined in
Built-in function.

Function prototype

void FreeRamDisk(int ramdiskno);

Description
FreeRamDisk destroy a ramdisk previously allocated with CreateRamDisk or
LoadRamDisk. All data stored on the ramdisk are permanently lost.

Example
CreateRamDisk(0,500000); // 500kb ramdisk
RDClean(0,"FATFS");
FreeRamDisk(0);

227
CreateRemboFloppy
CreateRemboFloppy — Create a bootable floppy image of Rembo
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void CreateRemboFloppy(str destpath, bool adminmode);

Description
This function saves the content of REMBO cache partition in a bootable floppy
image, that can later be written to a floppy disk with RestoreFloppyImage to run
REMBO in stand-alone mode.
Before creating a floppy image using this function, you should ensure that the cache
partition contains all necessary ressources needed by your scripts to run without
network connectivity. To check this, call SetOfflineMode start REMBO in off-line
mode and ensure that the configuration run smoothly.
CreateRemboFloppy creates a 1.44MB image file and stores this image in the file
specified by destpath. Typically, the destination path is somewhere under
cache://global/fdimages, so that it is uploaded to the server using the fast upload
protocol.
If the content of the cache partition does not fit on a floppy, an exception will be
thrown to indicate that there is not enough space on the floppy device. To reduce the
size of the cache partition (and the resulting floppy image), clean the cache partition
and run REMBO using only the functions and files that you would use when
running with the floppy.
The parameter adminmode determine whether the floppy version of REMBO will
start with administrator priviledges (extended start menu) or not.

Example
To create a bootable REMBO floppy and copy it afterwards to a floppy:
CreateRemboFloppy("cache://global/fdimages/remboot",true);
RestoreFloppyImage("cache://global/fdimages/remboot");

228
CreateRemboFloppy
To make the currently inserted floppy disk a bootable REMBO floppy (without
going through the server):
CreateRemboFloppy("floppy://0:rawfs/RawPartition01",true);

229
4.3. Hard-disk setup operations

DeviceCount
DeviceCount — Answer the number of connected devices
Synopsis

Defined in
Built-in function.

Function prototype

int DeviceCount(str devpath);

Description
This function returns the number of devices available on a specific URL prefix.
Allowed URL prefixes are

• disk, returns the number of fixed disks detected by REMBO


• floppy, returns the number of floppy disks detected by REMBO
• ram, returns the number of ramdisks supported by REMBO (not the number of
initialized ramdisk);
• loop, returns the number of loopback devices supported by REMBO (not the
number of initialized loopback devices).

Example
int hd = DeviceCount("disk");
Log((str)hd+" fixed disks detected<br>");

230
GetPrimaryPartitions
GetPrimaryPartitions — Retrieve the list of primary partitions
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str GetPrimaryPartitions(int disk);

Description
This function retrieves the list of the four primary partitions on the given hard disk.
The list is returned as a string of four space-separated entries describing the four
partitions. Each entry is made of two elements: the partition type (partition tag), and
the size in kilobytes of the partition (these two elements are separated with the
character ’:’).
Note that this function works well for standard cases, but that the detailed version
GetPrimaryPartitionsEx might be more appropriate for complex partition schemes.
Here is an example of primary partition string on a disk with two partitions: 500MB
for FAT, and 800MB for LINUX.
"BIGDOS:500000 EXT2FS:800000 EMPTY:0 EMPTY:0"

Partition tags describe the type of the partition. The type must be supported by your
operating system if you want to access the files stored on the partition from the
operating system. Here is a list of most commonly used tags:

• BIGDOS: this is the partition tag used by Windows for partitions up to 2 gigabytes
(16 bits FAT);
• FAT32: this is the partition tag used by Windows for partitions larger than 2
gigabytes (32 bits FAT);
• NTFS: this is the partition tag used by Windows NT and Windows 2000;
• EXT2: this is the partition tag used by Linux (second extended filesystem);
• LINUX-SWAP: this is the partition tag used by Linux for swap partitions;

231
GetPrimaryPartitions
• EXT: this tag denotes an extended partition, that is, a partition which space is
used to store logical partitions. It is recommended to have only one primary
extended partition.

You can transform the string returned by GetPrimaryPartitions in an array with a


call to ParsePartitions. This makes manipulations much simpler than dealing
with a string.

Partitions: how it works


Here is a brief explanation on how REMBO handles partitions, and how you should
create partitions to make sure that your partition layout is compatible with most
operating systems.
A partition is a region of the hard disk, identified by three elements: the first sector
of the partition (relative to the start of the disk), the number of sectors contained in
the partition, and the type of the partition. Under MS-DOS/Windows, partitions are
accessed as separate drive letters (C: is partition 1, D: is the first logical partition,
...). Under Linux, partitions are accessed as separate device files (/dev/hda1 is the
first primary partition, /dev/hda2 the second primary partition, /dev/hda5 the first
logical partition, ...).
Operating systems hide the complexity of the underlying partition layout to offer an
unified view of partitions: a hard-disk can be partitioned in an arbitrary number of
partitions (limited to 26 under MS-DOS/Windows). The operating system is
responsible for organizing the partitions on the disk in such a manner that other
operating systems can also read these partitions.
On the hard disk, partition information is stored in the very first sector of the disk,
called the Master Boot Record. This sector contains the master partition table, and a
small program which is executed when the hard disk is selected as the boot device.
This small program analyzes the partition table and branch execution to the
bootstrap code stored on the active (in REMBO: bootable) partition.
The master partition table has room for only four partition entries. That means that
it can describe up to four partitions on the hard-disk. These four partitions are called
primary partitions, and are accessed with the two Rembo-C functions
GetPrimaryPartitions and SetPrimaryPartitions, or the detailed versions
GetPrimaryPartitionsEx and SetPrimaryPartitionsEx.

A special partition type is used when more than four partitions must be created on a
single disk. This partition type is called an extended partition. Such a partition
defines a region of the disk that can be partitioned into an arbitrary number of units
called logical partitions. The information about these logical partitions is stored in
the first sector of the extended partition, in a table which format is similar to the
master partition table. This table of logical partitions has room for four partitions, as

232
GetPrimaryPartitions
the master partition table, but only two entries are used. The first entry defines one
logical partition, while the second entry defines the address of the sector containing
a new logical partition table, containing one entry plus one pointer to another
logical partition table, and so on...
Under REMBO, logical partitions are accessed through GetLogicalPartitions and
SetLogicalPartitions or the detailed versions GetLogicalPartitionsEx and
SetLogicalPartitionsEx. A third function, FindExtendedPartition, is used to
determine if there is an extended partition in the primary partitions list (logical
partitions can only be created if there is an extended primary partition). The actual
layout of logical partitions on the disk is handled internally by Rembo-C, so that the
user does not have to care about the linked list of logical partition tables. The
SetLogicalPartitions function takes a list of partition elements (tag:size)
separated by spaces and builds the logical partitions tables using the data in this list.
Primary partitions are numbered from 1 to 4, and logical partitions have numbers
from 5 up to the number of defined logical partitions + 5. You can modify your
partition layout with the appropriate Rembo-C functions, or by using the FDisk
wizard. To preserve the maximum compability with operating systems, FDisk keeps
entries 3 and 4 of the master partition table empty. Some operating systems only use
the two first primary partitions. If logical partitions need to be created, an extended
partition is created as primary partition 2, and logical partitions are inserted in this
extended partition.
Therefore, a partition layout created with FDisk and containing logical partitions
will always use the following numbering scheme: partition 1 is the first primary
partition, partition 2 is the extended partition, and partitions 5 and follow are the
logical partitions. If you want to access the partitions through a disk: URL, the
same numbers apply (i.e. disk://0:1 is the first primary partition, disk://0:5 is
the first logical partitions, ...). Remember that logical partitions exist only if there is
an extended partition in the primary partition table (use FindExtendedPartition to
determine the index of the extended partition).

Bootable partitions
As explained in the above paragraphs, the first sector of the hard disk contains the
Master Boot Record (MBR). This record is made of two parts: the bootstrap
program and the partition table. The task of the bootstrap program is to search the
partition table for an active partition (a.k.a. bootable partition), load the first sector
of the active partition and continue execution at the first byte of the loaded sector. If
there is no active partition, the MBR displays an error message and stops execution.
When you execute HDClean(0,0); under REMBO, the bootstrap program is
replaced by a default version created by REMBO. This default version is similar to
the MBR installed by MS-DOS or Windows, but has the additional capability of
displaying a customized message if there is no bootable partition, and to optionally

233
GetPrimaryPartitions
reboot. This can be used to display a message when the user disable the PXE
bootrom, and selects the hard-disk as the first boot device.
The active partition (bootable partition) can be selected with
SetBootablePartition and retrieved with GetBootablePartition. To select a new
bootable partition, call SetBootablePartition with a number from 1 to 4
corresponding to the primary partition number you want to make bootable. If you
select partition 0, REMBO will clear the bootable flag on all partitions, and the
computer will not be bootable anymore unless you are booting with REMBO
(HDBoot does not check bootable flags).

Examples
str p = GetPrimaryPartitions(0);
Log(p);
--> "BIGDOS:400000 FAT32:5000000 EMPTY:0 EMPTY:0"
var pa = ParsePartitions(p);
Log(sizeof(pa));
--> 4
Log(pa[0].type);
--> "BIGDOS"
Log(pa[0].size);
--> 400000
pa[1].size=6000000;
str newscheme = "";
for (int i=0;i<sizeof(pa);i++)
newscheme += pa[i].type+":"+(str)pa[i].size+" ";
SetPrimaryPartitions(0,newscheme);

234
GetPrimaryPartitionsEx
GetPrimaryPartitionsEx — Retrieves the list of primary partitions, with
more details
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str GetPrimaryPartitionsEx(int disk);

Description
This function returns a list of primary partitions, similar to GetPrimaryPartitions but
with additional details between curly braces:

• start=nsectors: offset of the partition in sectors.


• size=nsectors: size of the partition in sectors.
• active: for an active partition.

Details are very relevant if the partitions are not recorded in the right sequence in
the MBR or if there are unused sectors (holes) between them. In such cases, the
string returned by GetPrimaryPartitions doesn’t reflect the actual partition table.
Details are omitted if they are not necessary.
The following partition string is returned for a disk that has a FAT32 partition in the
lower 9 GB and an extended partition in the next 20 GB. But in the MBR the
extended partition is recorded before the FAT32 partition:
"EXT-LBA{start=18587205}:20482875 FAT32-LBA{active,start=63,size=18587142}:9293
EMPTY:0 EMPTY"

You must use SetPrimaryPartitionsEx and not SetPrimaryPartitions with this


string in order to re-create the same partition scheme during deployments.

235
GetLogicalPartitions
GetLogicalPartitions — Retrieve the list of logical partitions
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str GetLogicalPartitions(int disk);

Description
This function retrieves the list of all logical partitions defined for the hard disk
disk. Logical partitions are only valid if a primary extended partition exists.
You can use FindExtendedPartition to determine if there is an extended partition
before calling GetLogicalPartitions or SetLogicalPartitions.
The list returned by GetLogicalPartitions can be transformed in an array with a
call to ParsePartitions.
See the manual page of GetPrimaryPartitions for more information about disk
partitions.

Example
if (FindExtendedPartition(0)>0) {
str lp = GetLogicalPartitions(0);
var lpa= ParsePartitions(lp);
Log((str)sizeof(lpa)+" logical partitions are defined<br>");
int totalsize = 0;
for (int i=0;i<sizeof(lpa);i++)
totalsize += lpa[i].size;
Log("Total size of logical partitions: "+
SizeToStr(totalsize*1024)+"<br>");

236
GetLogicalPartitionsEx
GetLogicalPartitionsEx — Returns a detailed description of logical
partitions
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str GetLogicalPartitionsEx(int disk);

Description
This function retrieves the list of all logical partitions defined for the hard disk
disk. Logical partitions are only valid if a primary extended partition exists.
Like GetPrimaryPartitionsEx this function returns details about partitions that are
not available with the simple function GetLogicalPartitions.
See the manual page of GetPrimaryPartitionsEx for the description of additional
fields.
See the manual page of GetPrimaryPartitions for more information about disk
partitions.

237
FindExtendedPartition
FindExtendedPartition — Retrieve the index of the extended partition
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

int FindExtendedPartition(int disk);

Description
This function returns the index of the primary extended partition, or 0 if there is no
extended partition.
Use this function to determine if there are logical partitions on a hard disk.
See the manual page of GetPrimaryPartitions for more information about disk
partitions.

Example
if (FindExtendedPartition(0)>0) {
str lp = GetLogicalPartitions(0);
var lpa= ParsePartitions(lp);
Log((str)sizeof(lpa)+" logical partitions are defined<br>");
int totalsize = 0;
for (int i=0;i<sizeof(lpa);i++)
totalsize += lpa[i].size;
Log("Total size of logical partitions: "+
SizeToStr(totalsize*1024)+"<br>");

238
ParsePartitions
ParsePartitions — Build an array from a list of partitions
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var ParsePartitions(str partlist);

Description
This function splits a list of partitions (a string) and builds an array containing all
partition information parsed and structured.
Each element of the array corresponds to one partition definition, stored in a
structure with two members: str type (the type of the partition, as described in the
manual page of GetPrimaryPartitions), and int size (the size of the partition in
kilobytes).
The string passed as an argument to ParsePartitions must have the following
format:
PTYPE:PSIZE PTYPE:PSIZE PTYPE:PSIZE ...

See the manual page of GetPrimaryPartitions for more information about disk
partitions.

Example
str p = GetPrimaryPartitions(0);
var pa= ParsePartitions(p);
for (int i=0;i<sizeof(pa);i++)
Log("Partition "+(str)i+": "+SizeToStr(pa[i].size*1024)+
" ("+pa[i].type+")<br>");

239
ParsePartitions
See also
See also DescribePartitions.

240
DescribePartitions
DescribePartitions — Build a list of partitions from an array
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str DescribePartitions(var partarray);

Description
This function builds a list of partitions (a string) from an array containing all
partition information, as returned by ParsePartitions.
Each element of the source array should be a structure, with at least two members:
str type (the type of the partition, as described in the manual page of
GetPrimaryPartitions), and int size (the size of the partition).
The string returned by DescribePartitions will have a format acceptable for a call
to SetPrimaryPartitions and SetLogicalPartitions.

Example
str p = GetPrimaryPartitions(0);
var pa= ParsePartitions(p);
pa[0].size += 1000;
pa[1].size -= 1000;
str newp = DescribePartitions(pa);
SetPrimaryPartitions(0, newp);

See also
See also ParsePartitions.

241
FitPartitions
FitPartitions — Expand wildcards in a list of partitions
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str FitPartitions(str partlist, int totalsize);

Description
This function analyze a partition list in the usual format used by
SetPrimaryPartitions and SetLogicalPartitions, and resolves wildcards (i.e.
sizes defined as *) by sharing the available space among partitions.
The repartition of available space follows the same semantics as HTML 3.0 table
columns for instance: First, all partitions with a fixed size are substracted from the
totalsize. Then, the remaining size is shared proportionally amoung all
partitions that have a size with a *. If the * is preceeded by a number, the number is
interpreted as a proportionality coefficient.
Note that SetPrimaryPartitions and SetLogicalPartitions implicitely call
FitPartitions if a wildcard is used in the partition definition string, so there is
normally no need to use it explicitely.

Example
str ex1 = FitPartitions("DIAGS:16 NTFS:* NTFS:*", 1016);
// ex1 = "DIAGS:16 NTFS:500 NTFS:500"
str ex2 = FitPartitions("NTFS:2* NTFS:*", 900);
// ex2 = "NTFS:600 NTFS:300"

242
GetBootablePartition
GetBootablePartition — Retrieve the list of primary partitions
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

int GetBootablePartition(int disk);

Description
This function retrieves the index of the active primary partition (1-4), or 0 if there is
no bootable partition.
See the manual page of GetPrimaryPartitions for more information about bootable
partitions.

Example
if (GetBootablePartition(0)==0)
Log("There is no bootable partition!<br>");

243
SetPrimaryPartitions
SetPrimaryPartitions — Define primary partitions
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str SetPrimaryPartitions(int disk, str partlist);

Description
These functions write the primary partition table with the partition layout given in
partlist. This layout must be of the form "PTYPE:PSIZE PTYPE:PSIZE ...".
For complex partition schemes, see the detailed version SetPrimaryPartitionsEx that
accepts additional fields between curly braces.
No more than four primary partitions can be created. It is recommended to create
only two primary partitions (one real partition and one extended partition), and use
logical partitions to define more partitions.
See the manual page of GetPrimaryPartitions for more information about partitions
and examples.

244
SetPrimaryPartitionsEx
SetPrimaryPartitionsEx — Define primary partitions, with details
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str SetPrimaryPartitionsEx(int disk, str partlist);

Description
These functions write the primary partition table with the partition layout given in
partlist. This layout must be of the form "PTYPE:PSIZE PTYPE:PSIZE ...".
Additional details as provided by GetPrimaryPartitionsEx can be provided between
curly braces, before the colon.
No more than four primary partitions can be created. It is recommended to create
only two primary partitions (one real partition and one extended partition), and use
logical partitions to define more partitions.
See the manual page of GetPrimaryPartitions for more information about partitions
and examples.

245
SetLogicalPartitions
SetLogicalPartitions — Define logical partitions
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void SetLogicalPartitions(int disk, str partlist);

Description
This function writes the logical partition tables with the partition layout given in
partlist. This layout must be of the form "PTYPE:PSIZE PTYPE:PSIZE ...".
See the detailed version SetLogicalPartitionsEx for more complex cases.
A primary extended partition must be defined in order to create logical partitions.
You can use FindExtendedPartition to check that a primary extended partition
exists.
You cannot create extended logical partitions.
The accumulated size of logical partitions must not exceed the size of the primary
extended partition. You can create as many partitions as you want, but operating
systems may limit the number of logical partitions.
See the manual page of GetPrimaryPartitions for more information about partitions
and examples.

Example
Commands to create the following layout: 500MB BIGDOS (C:), 800MB FAT32
(D:), 800MB FAT32 (E:):
SetPrimaryPartitions(0,"BIGDOS:500000 EXT:1600000");
SetLogicalPartitions(0,"FAT32:800000 FAT32:800000");
SetBootablePartition(0,1); // C: bootable
HDClean(0,0); // Clean MBR bootstrap program

Commands to create the following layout: 20MB EXT2 (/boot), 500MB EXT2 (/),
1500MB EXT2 (/usr), 128MB LINUX-SWAP (swap):

246
SetLogicalPartitions
SetPrimaryPartitions(0,"EXT2:20000 EXT:2128000");
SetLogicalPartitions(0,"EXT2:500000 EXT2:1500000 LINUX-SWAP:128000");

247
SetLogicalPartitionsEx
SetLogicalPartitionsEx — Define logical partitions, with details
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void SetLogicalPartitionsEx(int disk, str partlist);

Description
This function writes the logical partition tables with the partition layout given in
partlist. This layout must be of the form "PTYPE:PSIZE PTYPE:PSIZE ...".
With this function, details as provided by GetPrimaryPartitionsEx or
GetLogicalPartitionsEx can be added between curly braces, before the colon.

A primary extended partition must be defined in order to create logical partitions.


You can use FindExtendedPartition to check that a primary extended partition
exists.
You cannot create extended logical partitions.
The accumulated size of logical partitions must not exceed the size of the primary
extended partition. You can create as many partitions as you want, but operating
systems may limit the number of logical partitions.
See the manual page of GetPrimaryPartitions for more information about partitions
and examples.

248
SetBootablePartition
SetBootablePartition — Define the bootable partition
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void SetBootablePartition(int disk, int part);

Description
This function sets the active partition in the primary partition table. You can use a
number between 1 and 4, or 0 if you want to clear the active flag on all primary
partitions.
See the manual page of GetPrimaryPartitions for more information about partitions
and examples.

249
SetOfflineMode
SetOfflineMode — Setup the hard-disk to boot Rembo by default
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void SetOfflineMode(int disk, int part, bool adminmode);

Description
This function writes a special boot record on the specified hard-disk primary
partition, that allows REMBO to start in off-line mode when there is no network
connectivity. For more informations on the use of off-line mode, see Section 2.7.1
in REMBO Client Administration Manual. To write the off-line mode boot code to
the hard-disk Master Boot Record (MBR), use partition 0.
The parameter adminmode specifies whether REMBO should be started by
default with administrator priviledges or not in off-line mode.
To revert the effect of this function and remove the off-line mode, you must rewrite
a standard boot sector. In the case of the Master Boot Record, this can be done
using by using the standard FDISK program (from a MS-DOS floppy), or with the
following Rembo-C command:
HDClean(0,0);

See also
See also Section 2.7.1 in REMBO Client Administration Manual and
WriteOfflineCode.

250
HDClean
HDClean — Quick-format a partition
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void HDClean(int disk, int part);

Description
HDClean creates a new filesystem structure on a partition (aka Quick-Format). The
filesystem to install is automatically determined from the partition type. The
partition is identified by the parameters disk and part. disk is the index of the
hard-disk and part is the index of the partition in this hard-disk. First hard disk is
0, and first usable partition is 1.
You can clean the Master Boot Record (MBR) (i.e. reinstall a fresh copy of the
bootstrap program without destroying partition table information) by clearing
partition 0 with HDClean(0,0);. The bootstrap program will be replaced with a
default version created with REMBO. This default bootstrap program can display
an error message if there is no active partition, and optionally reboot. To set the
custom error message, write the message in the file disk://0:0/BootMessage. To
activate reboot on error, write the number of 100th seconds to wait before rebooting
in the file disk://0:0/RebootDelay.
See the manual page of GetPrimaryPartitions for more information about partitions
and MBR.

Example
This example installs a new MBR with the custom error message This computer can
only boot from the network and a reboot delay of 5 seconds (500 hundreds of
second). The active partition flag is then removed from all partitions to make sure
that the error message will be displayed if the user tries to select the hard disk as the
first boot device:
SaveText("This computer can only boot from the network",
"disk://0:0/BootMessage");
SaveText("500","disk://0:0/RebootDelay");
HDClean(0,0);

251
HDClean
SetBootablePartition(0,0);

See also
See also DeviceClean.

252
HDCheck
HDCheck — Detect and fix corruptions in a filesystem
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void HDCheck(int disk, int part);

Description
HDCheck checks and fixes the filesystem structure on a partition (aka ScanDisk). The
partition is identified by the parameters disk and part. disk is the index of the
hard-disk and part is the index of the partition in this hard-disk. First hard disk is
0, and first usable partition is 1.
As no user interaction is expected, the filesystem integrity is recovered by a
destructive method: all blocks not allocated in a properly built file are freed, and all
incorrect directory entries are deleted. This ensures a safe filesystem state even in
case of system crash, but may lead to loss of data for all files that were not properly
flushed at the time the computer was stopped.
This function clears the filesystem dirty flag, and thus avoid the automatic start of
the operating system own ScanDisk or fsck program.
Currently, this function is only supported on FAT-based filesystems.

Example
When using self-healing on a partition, it is safer first to check and fix possible
filesystem corruptions in the target partition:
HDCheck(0,1);
Synchronize("cache://global/myimage","disk://0:1/","b");

See also
See also DeviceCheck.

253
BuildDiskImage
BuildDiskImage — Build a compressed image of a disk partition
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void BuildDiskImage(int disk, int part, str imagepath);

Description
BuildDiskImage reads the full content of the disk partition given as argument and
makes a compressed image of it. The resulting image is stored in the file
imagepath on the server (the path must start with net: or preferably cache:).
If the file imagepath already exists, BuildDiskImage first deletes the image and
then start the image creation process.
If you use a cache: path, the hard disk image will be sent to the server using the
FAST protocol, which is more efficient that the protocol used by net:. Note that
cache: paths work even if no cache partition is setup.

Example
BuildDiskImage(0,1,"cache://global/winnt");

Is equivalent to
if (FileExists("cache://global/winnt"))
RemoveFile("cache://global/winnt");
Synchronize("disk://0:1","cache://global/winnt","");

254
RestoreDiskImage
RestoreDiskImage — Restore a disk partition from a compressed image
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void RestoreDiskImage(int disk, int part, str imagepath);

Description
RestoreDiskImage reset the content of the disk partition given as argument
according to the content of a compressed image previously created with
BuildDiskImage. Two separate actions are performed by RestoreDiskImage: the
partition is quick-formatted, and then the image is restored.
If imagepath starts with cache:, and a local cache partition exists, the file is first
downloaded with the MCAST protocol (multicast download protocol) into the
cache partition, and then accessed from the cache partition. Note that if the variable
Settings.UseMCAST is set to false, the same protocol as net: is used (i.e. unicast
protocol), but the image is still downloaded into the cache partition.
Note: you do not need to call HDClean to clean the target partition before restoration
because this is done by RestoreDiskImage.
RestoreDiskImage is a shortcut to the more general Synchronize function. For
example, when you call
RestoreDiskImage(0,1,"cache://global/myimage");, Rembo
actually executes
HDClean(0,1);
Synchronize("cache://global/myimage","disk://0:1/","b");

Example
RestoreDiskImage(0,1,"cache://global/winnt");

is equivalent to

255
RestoreDiskImage
HDClean(0,1);
Synchronize("cache://global/winnt","disk://0:1","b");

256
CreateRemboCDRom
CreateRemboCDRom — Create a bootable ISO CD-Rom image of Rembo
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void CreateRemboCDRom(str destpath, bool adminmode);

Description
This function saves the content of REMBO cache partition in a bootable ISO
CD-Rom image, that can later be written to a CD-Rom in order to get a stand-alone
version of REMBO.
Before creating an ISO image using this function, you should ensure that the cache
partition contains all necessary ressources needed by your scripts to run without
network connectivity. To check this, call SetOfflineMode start REMBO in off-line
mode and ensure that the configuration run smoothly.
The resulting ISO Image file will be created at the destpath specified as
argument, and should be at least as big as the sum of all files used by the scripts
(including the compressed hard-disk images). Typically, the destination path is
somewhere under cache://global, so that it is uploaded to the server using the fast
upload protocol.
The parameter adminmode determine whether the floppy version of REMBO will
start with administrator priviledges (extended start menu) or not.

See also
See also Section 2.7.2 in REMBO Client Administration Manual.

257
4.4. Protected partitions handling

ClearProtectedPartitions
ClearProtectedPartitions — Remove all protected partitions by
removing the BEER sector
Synopsis

Defined in
Built-in function.

Function prototype

void ClearProtectedPartitions(int diskno);

Description
This function clears the last physical sector of the hard disk, that includes the
definition of protected partitions (the BEER). The parameter diskno specifies the
disk on which the operation should be performed.
Note that clearing the protected partitions does not in itself unhide the protected
area of the hard disk. You should use the UnhideProtectedPartitions function do
restore the apparent size of the hard-disk to its physical size.

Example
To remove any protected partition and make the hard-disk apparent size
permanently equal to the physical size, use the following commands:
ClearProtectedPartitions(0);
UnhideProtectedPartitions(0,false);

See also
See also UnhideProtectedPartitions.

258
GetProtectedPartitions
GetProtectedPartitions — Retrieve the list of protected partitions
Synopsis

Defined in
Built-in function.

Function prototype

str GetProtectedPartitions(int diskno);

Description
This function returns a string that describes the protected partitions on the specified
hard-disk, as read from the BEER sector (the very last physical sector of the
hard-disk). This description has a format similar to the one returned by
GetPrimaryPartitions and GetLogicalPartitions, except that the partition
identifier is not the partition type (which is not specified for protected partitions) but
the protected partition ID string.
As protected partitions typically grow from the end of the disk to the beginning,
they are listed in this order in the description string (the partition nearest to the end
of the disk is the first in the description string).
In addition to the partition ID string, the following optional attributes may be
appended between braces:

• BOOT_AS_A is a flag that specifies that the protected partition is intended to be


bootable as a virtual floppy-disk.
• HIDDEN is a flag that specifies that the protected partition should not be listed in
the boot menu.
• EMPTY is a flag that specifies that the protected partition is unused.
• THIS_BOOT is a flag that specifies that the protected partition should be used as
the default boot, before the any regular partition.
• READ_ONLY is a flag that specifies that the protected partition should be mounted
read-only.
• DIAG_SERV is a flag that indicates that the protected partition includes a hardware
diagnostic service or similar tool.

259
GetProtectedPartitions
• AREA_B is a flag that indicates that the protected partition should includes a
virtual floppy-disk that should be mounted as drive B on next boot.
• ID is a 16-bit numeric identifier that uniquely identifies the protected partition
vendor, or remains zero by default.
• LoadSect is a 32-bit number that specifies the number of boot sectors that should
be loaded for booting the partition. The default value is 1.
• LoadAddr is a 32-bit number that specifies the physical address at which the boot
sectors should be loaded. The default value is 7c00.
• Start is a 32-bit number that specifies the absolute start sector of the protected
partition on the hard-disk. The default start value is such that the partition ends
exactly at the start of the previous partition.
• Odd is a flag indicates that the partition has an odd number of sector, that has
been rounded down to represent it in kilobytes in the description string.

If there is no BEER on the hard-disk, a call to this function will raise an error.
Use GetExtDiskInfo first to determine if there is a BEER on the hard-disk.

Example
var einfo = GetExtDiskInfo(0);
if(einfo.ProtPartEnabled)
Print(GetProtectedPartitions(0))
---> "SECRET:16384 RAB{BOOT_AS_A,THIS_BOOT}:1024000"

See also
See also SetProtectedPartitions.

260
SetProtectedPartitions
SetProtectedPartitions — Define protected partitions
Synopsis

Defined in
Built-in function.

Function prototype

void SetProtectedPartitions(int diskno, str partHandle);

Description
This function updates the BEER sector (the very last physical sector of the
hard-disk) to define new protected partitions, according to a description string. The
description has a format similar to the one used by SetPrimaryPartitions and
SetLogicalPartitions, except that the partition identifier is not the partition type
(which cannot be specified for protected partitions) but the protected partition ID
string.
As protected partitions typically grow from the end of the disk to the beginning,
they must be listed in this order in the definition string (the first partition of the
string will be created nearest to the end of the disk). Additional attributes can be
used to specify the absolute position of individual protected partitions and other
properties. See the documentation of GetProtectedPartitions for an exhaustive
list of protected partition attributes.
Once created, a protected partition can be formatted and used as a regular partition
under REMBO, using DeviceCleanForce or DeviceCleanEx. Protected partitions
are numbered starting with 100. Rembo lets you define up to six protected partitions
per disk.

Note that defining protected partitions is a distinct operation of actually


protecting them by hiding the corresponding portion of the hard-disk. Use
function HideProtectedPartitions to do so.
Protected partitions can be used on any computer with ATA-5 or more recent disks.
However, in order to have the bootable protected partitions listed in the BIOS boot
menu, support for protected partitions is required in the computer BIOS, which is
currently very seldom. However, REMBO provides an easy alternate mean that can
be used safely on almost any computer. Use function WriteRemboProtectedMBR to
write a special boot sector that will be able to boot into a protected partition, and if

261
SetProtectedPartitions
needed, protect the MBR using the BIOS setup. This will make it very difficult
avoid having the computer booting in the protected partition.

Example
To create a DOS bootable protected partition, use the following commands:
// Create a protected partition of 2.88 MB
SetProtectedPartitions(0, "DOSBOOT{BOOT_AS_A,THIS_BOOT}:2880");

// Format the partition according to the image format


var devinfo = DeviceGetInfo("cache://global/myboot.img");
DeviceCleanEx("disk://0:100", devinfo);

// Restore the content of the image on the partition


Synchronize("cache://global/myboot.img","disk://0:100","b");

// Write a MBR that can boot into the protected partition


WriteRemboProtectedMBR(0);

// Resize the hard disk to hide the protected area


HideProtectedPartitions(0,false);

To create a Rembo bootable protected partition with the same content as the current
cache partition, use the following commands:
// Create a protected partition of 8 MB
SetProtectedPartitions(0, "REMBO{BOOT_AS_A,THIS_BOOT}:8192");

// Format the partition in FAT16


DeviceCleanForce("disk://0:100","FAT16");

// Clone the cache partition to a loopback file called rembohd


var ci = DeviceClone("disk://0:-1","disk://0:100/rembohd");
while(MoreRemboClone(ci) < 100);

// Write a boot sector into the protected partition to boot on rembohd


WriteHDCode("disk://0:100");

// Write a MBR that can boot into the protected partition


WriteRemboProtectedMBR(0);

// Resize the hard disk to hide the protected area


HideProtectedPartitions(0,false);

262
SetProtectedPartitions
See also
See also GetProtectedPartitions and HideProtectedPartitions.

263
GetBEER
GetBEER — Retrieve the protected partitions global parameters
Synopsis

Defined in
Built-in function.

Function prototype

var GetBEER(int diskno);

Description
This function returns a structure describing global parameters of the protected area
of the hard disk, as read from the BEER sector (the very last physical sector of the
hard-disk). This information includes the number of partitions, the disk geometry
and the absolute start address of the protected area of the hard disk.

If there is no BEER on the hard-disk, a call to this function will raise an error.
Use GetExtDiskInfo first to determine if there is a BEER on the hard-disk.

Example
var einfo = GetExtDiskInfo(0);
if(einfo.ProtPartEnabled)
LogVar(GetBEER(0))

See also
See also SetBEER.

264
SetBEER
SetBEER — Update the protected partitions global parameters
Synopsis

Defined in
Built-in function.

Function prototype

var SetBEER(int diskno, var beer);

Description
This function updates the global parameters describing the protected area of the
hard disk, in the BEER sector (the very last physical sector of the hard-disk). The
structure passed as argument beer is typically the edited result of a call to GetBEER.
This function is seldom used, since SetProtectedPartitions automatically fills
the BEER sector with standard values.

Example
// Read the BEER sector
var beer = GetBEER(0);

// Extend the protected area of 100 sectors


beer.HostProtectedAreaStartLow -= 1000;

// Reqrite the BEER sector


SetBEER(0, beer);

See also
See also GetBEER.

265
GetBEEREntry
GetBEEREntry — Retrieve the parameters of a given protected partition
Synopsis

Defined in
Built-in function.

Function prototype

var GetBEEREntry(int diskno, int entry);

Description
This function returns a structure describing the details of the selected protected
partition of the hard-disk, as read from the BEER sector (the very last physical
sector of the hard-disk). Most attributes can also be retrieved using
GetProtectedPartitions, but in some cases it might be more convenient to use
them directly instead of parsing the whole definition string.
The parameter entry is the index in the BEER of the protected partition whose
attributes are requested, starting with zero. The number of protected partitions can
be retrieved in the structure returned by GetBEER.

If there is no BEER on the hard-disk, a call to this function will raise an error.
Use GetExtDiskInfo first to determine if there is a BEER on the hard-disk.

Example
var einfo = GetExtDiskInfo(0);
if(einfo.ProtPartEnabled) {
int nProtPart = GetBEER(0).NumberOfEntries;
Printf("%d protected partitions found:<br>", nProtPart);
for(int i = 0; i < nProtPart; i++)
LogVar(GetBEEREntry(0, i))
} else
Print("There are no protected partitions<br>");

See also
See also GetProtectedPartitions, GetBEER and SetBEEREntry.

266
SetBEEREntry
SetBEEREntry — Update the parameters of a given protected partition
Synopsis

Defined in
Built-in function.

Function prototype

var SetBEEREntry(int diskno, int entry, var beerEntry);

Description
This function updates the global parameters describing a specific protected partition
of the hard disk, in the BEER sector (the very last physical sector of the hard-disk).
The structure passed as argument beerEntry is typically the edited result of a
call to GetBEEREntry.
This function is seldom used, since SetProtectedPartitions automatically fills
the BEER sector with standard values. One possible use is to force the start of a
protected partition to match the start of an existing (normal) partition, so as to
protect it without loosing its content.

Example
// Retrieve information about partitions
var partinfo = DeviceInfo("disk://0:4");
var beerEntry = GetBEEREntry(0,0);

// Overlap both partitions


beerEntry.AreaStartLow = partinfo.startSector;
beerEntry.AreaSizeLow = partinfo.totalSectors;

// Update the protected partition, hide it


SetBEEREntry(0,0,beerEntry);
HideProtectedPartitions(0,false);

// Note: partition 4 should now be removed from


// the regular partition table

267
SetBEEREntry
See also
See also SetProtectedPartitions and GetBEEREntry.

268
HideProtectedPartitions
HideProtectedPartitions — Hide protected partitions by reducing the disk
size
Synopsis

Defined in
Built-in function.

Function prototype

void HideProtectedPartitions(int diskno, bool volatile);

Description
This function is used to effectively hide the protected area of the hard disk, to
prevent any access by the operating system or any tool not aware of ATA protected
area. Disk protection works by reprogramming the hard-disk apparent size to a
smaller value that the physical size of the media. This will make the disk look really
smaller, even to the disk-manager applications, and no access is possible to the
hidden part of the hard disk.
This function only works if the hard-disk implements the protected area feature,
part of the ATA-5 standard. This is normally the case on most reasonnably recent
hard-disks. You can check if a hard-disk is capable of handling protected partitions
by calling GetExtDiskInfo and checking the value of the ProtPartCapable
boolean flag.
By default, the protection will remain effective after a reboot or a power cycle (it is
non-volatile). However, if the volatile parameter is set to true, the protection
will only be effective until the next power cycle.
Although a non-volatile disk protection is immediately applied by REMBO (so as
to secure the area in case of unexpected power shutdown), REMBO always
implicitely use a volatile disk deprotection to be able to access the protected
partitions. The volatile protection is implicitely restored if needed when REMBO
boot into the operating system.
After a change of to the size of the protected area, it is necessary to rehide it using
this command, so as to update the apparent size of the hard disk.

By definition in the ATA protocol, it is only possible to hide or unhide the


protected area in a non-volatile manner once per power cycle. Subsequent

269
HideProtectedPartitions
attemps will always result in a Protocol error, and the operation will be
cancelled.

Example
var einfo = GetExtDiskInfo(0);
if(einfo.ProtPartCapable) {
// Create a protected partition of 1.44 MB
SetProtectedPartitions(0, "SECRET:1440");

// Resize the hard disk to hide the protected area


HideProtectedPartitions(0,false);
} else {
Print("Protected partitions are not supported<br>");
}

See also
See also GetExtDiskInfo, SetProtectedPartitions,
UnhideProtectedPartitions.

270
UnhideProtectedPartitions
UnhideProtectedPartitions — Unhide protected partitions by restoring
the disk size
Synopsis

Defined in
Built-in function.

Function prototype

void UnhideProtectedPartitions(int diskno, bool volatile);

Description
This function is used to unhide the protected area of the hard disk, in order to
restore the hard-disk apparent size to the actual physical size of the media.
This function will return an error if the hard-disk does not implement the protected
area feature, part of the ATA-5 standard. You can check if a hard-disk is capable of
handling protected partitions by calling GetExtDiskInfo and checking the value of
the ProtPartCapable boolean flag.
By default, the deprotection will remain effective indefinitely (it is non-volatile).
However, if the volatile parameter is set to true, the deprotection will only be
effective until the next power cycle, and the protected area will be invisible again
afterwards.

By definition in the ATA protocol, it is only possible to hide or unhide the


protected area in a non-volatile manner once per power cycle. Subsequent
attemps will always result in a Protocol error, and the operation will be
cancelled.

Example
To remove any protected partition and make the hard-disk apparent size
permanently equal to the physical size, use the following commands:
ClearProtectedPartitions(0);
UnhideProtectedPartitions(0,false);

271
UnhideProtectedPartitions
See also
See also ClearProtectedPartitions, HideProtectedPartitions.

272
WriteRemboProtectedMBR
WriteRemboProtectedMBR — Write a MBR that can boot into a protected
partition
Synopsis

Defined in
Built-in function.

Function prototype

void WriteRemboProtectedMBR(int targetDiskNo);

Description
This function rewrites the MBR (master boot record) of the primary hard-disk to
allow the boot on a protected partition. Using this special MBR, no special BIOS is
required to boot on a protected partition. The argument targetDiskNo specifies
the hard-disk that should be searched for protected partitions.
This special MBR will read the BEER sector of the specified hard-disk, search for
any protected partition with the flag THIS_BOOT turned on (or for any protected
partition with the flag BOOT_AS_A, if the F9 key has been depressed during the
boot sequence). If such a protected partition is found, the MBR will install the
proper disk emulation and boot into the partition. If no protected partition is found,
or if none has a boot flag turned on, the MBR will boot on the default partition
marked as active in the regular partition table.
This special MBR uses a volatile deprotection to access the protected area of the
hard-disk. The software in the protected partition should normally reprotect the
hard-disk (in a volatile way) if it is to be hidden again when the protected service
has completed its task.

The code written to the MBR by this function is copyrighted by Rembo


Technology SaRL, Geneva, Switzerland and cannot be reused on an arbitrary
number of computer without a proper licensing agreement.
To restore a standard MBR on the hard-disk, simply use HDClean(0,0).

Example
To create a DOS bootable protected partition, use the following commands:
// Create a protected partition of 2.88 MB

273
WriteRemboProtectedMBR
SetProtectedPartitions(0, "DOSBOOT{BOOT_AS_A,THIS_BOOT}:2880");

// Format the partition according to the image format


var devinfo = DeviceGetInfo("cache://global/myboot.img");
DeviceCleanEx("disk://0:100", devinfo);

// Restore the content of the image on the partition


Synchronize("cache://global/myboot.img","disk://0:100","b");

// Write a MBR that can boot into the protected partition


WriteRemboProtectedMBR(0);

// Resize the hard disk to hide the protected area


HideProtectedPartitions(0,false);

To create a Rembo bootable protected partition with the same content as the current
cache partition, use the following commands:
// Create a protected partition of 8 MB
SetProtectedPartitions(0, "REMBO{BOOT_AS_A,THIS_BOOT}:8192");

// Format the partition in FAT16


DeviceCleanForce("disk://0:100","FAT16");

// Clone the cache partition to a loopback file called rembohd


var ci = DeviceClone("disk://0:-1","disk://0:100/rembohd");
while(MoreRemboClone(ci) < 100);

// Write a boot sector into the protected partition to boot on rembohd


WriteHDCode("disk://0:100");

// Write a MBR that can boot into the protected partition


WriteRemboProtectedMBR(0);

// Resize the hard disk to hide the protected area


HideProtectedPartitions(0,false);

See also
See also SetProtectedPartitions, HDClean.

274
4.5. Booting functions

HDBoot
HDBoot — Boot the computer on the specified partition
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void HDBoot(int disk, int part);

Description
Use HDBoot to start the operating system located on the given partition. The
partition is identified by the parameters disk and part.disk is the index of the
hard-disk and part is the index of the partition in this hard-disk. First hard disk is
0, and first usable partition is 1.
The selected partition does not need to have the active partition flag set. You can
start any partition which has a valid and bootable operating system installed on it.
This can be used as a security feature: make the hard disk non bootable with
SetBootablePartition(0,0); and the only way to start any operating system is to
use REMBO.

275
RDBoot
RDBoot — Let the computer boot on the ramdisk as if it was a floppy
Synopsis

Defined in
RDBoot: /plugins/utils.rbx

RamDiskBoot: Built-in function.

Function prototype

void RDBoot(int ramdiskno);


void RamDiskBoot(int ramdiskno, bool unloadpxe);

Description
RDBoot lets the computer boot on the floppy disk image stored on the given ramdisk.
REMBO is unloaded from the memory, except for a tiny resident portion that stays
at the top of the conventional memory. The ramdisk image is stored at the very top
of the extended memory. The resident code emulates a floppy disk on the ramdisk at
the BIOS-level (thus preventing the use of the floppy disk).
RamDiskBoot is the low-level function used by RDBoot to actually perform the boot.
The additional parameter unloadpxe can be used to specify whether the PXE
bootrom must be completely unloaded (value true) or if the UNDI part of the
bootrom should be kept in memory (value false). When called from RDBoot,
unloadpxe is set to true.

Example
LoadRamDisk(0,"cache://global/myfloppy");
CreateTextFile("ram://0/autoexec.bat","@Echo off\r\n");
RDBoot(0);

276
LXBoot
LXBoot — Launch a Linux kernel
Synopsis

Defined in
LXBoot:/plugins/utils.rbx

LinuxBoot:Built-in function

Function prototype

void LXBoot(str kernel, str initrd, str cmdline);


void LinuxBoot(str kernelpath, str initrdpath, str cmdline, bool
unloadpxe);
void LinuxBootEx(var krn, var initrd, str args, bool unloadpxe);

Description
LXBoot loads a linux kernel into the memory, installs a Linux initial ramdisk (initrd)
and starts the kernel with the specified command-line arguments. The parameter
kernel must be a valid URL pointing to a standard Linux kernel image (in zImage
or bzImage format). The parameter initrd can be empty if no initial ramdisk is
wanted, or must be a valid URL pointing to a possibly compressed initrd ramdisk
image. The command line is given as is to the kernel; for more information on valid
command-line arguments, refer to the Linux documentation.
LinuxBoot is the low-level function used by LXBoot to actually boot the kernel. If
you call LinuxBoot directly, you can use the unloadpxe parameter to keep the
UNDI part of the PXE bootrom loaded into the memory under Linux. This might be
required if you are running the UNDI network driver as the network interface driver.
When LinuxBoot is called from LXBoot, unloadpxe is set to true.
LinuxBootEx is an alternate interface to boot a linux kernel and an optional initial
ramdisk, that have been previously loaded into memory (in a binary object). This
makes it possible to remote-boot a Linux configuration downloaded using multicast
on a diskless computer, by loading the kernel and initial ramdisk using the
DownloadFile function (see the example below).

If your kernel does not detect all the memory installed in the computer, you should
add "mem=xxxM" in the kernel command line to tell the kernel how much memory is
installed (replace xxx with the amount of memory in megabytes). You can use
GetMemoryInfo to create the "mem=xxxM" in a Rembo-C script.

277
LXBoot

If the size of the uncompressed initial ramdisk is larger than 4096KB for 2.0
kernels or 32768KB for 2.2 kernels, you must specify it to the kernel using the
ramdisk= command-line argument. Otherwise, the kernel will complain about
an invalid compressed format.

Example
NFS boot:
LXBoot("cache://group/zImage", "",
"root=/dev/nfs nfsroot=192.168.1.3:/export/nfsroot");

Initial ramdisk boot:


LXBoot("cache://group/zImage", "cache://group/initrd.gz",
"root=/dev/ram ramdisk=65536");

Initial ramdisk boot using multicast on a diskless computer:


var kernel = DownloadFile("net://group/zImage");
var initrd = DownloadFile("net://group/initrd.gz");
LinuxBootEx(kernel, initrd,
"root=/dev/ram ramdisk=65536", true);

Disk-based boot:
LXBoot("cache://group/zImage", "", "root=/dev/hda1");

278
FloppyBoot
FloppyBoot — Let the computer boot on a floppy disk
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void FloppyBoot(void);

Description
FloppyBoot lets the computer boot on the floppy disk drive. REMBO is unloaded
from the memory, and the computer starts normally.

See also
See also RDBoot.

279
Reboot
Reboot — Reboot the computer
Synopsis

Defined in
Built-in function.

Function prototype

void Reboot(void);

Description
Reboot shutdowns REMBO and reboot the computer. This function flushes all
unsaved data to the disk and terminate all the running processes.

280
PowerOff
PowerOff — Turn off the computer
Synopsis

Defined in
Built-in function.

Function prototype

void PowerOff(void);

Description
PowerOff will gracefully shutdown REMBO and turn the computer off if the BIOS
supports the Soft Power-off functionality. This function flushes all unsaved data to
the disk and terminate all the running processes.
The global variable SystemInfo.APM can be used to determine whether your
computer supports soft power-off or not.

281
BIOSBoot
BIOSBoot — Resume the BIOS boot process
Synopsis

Defined in
Built-in function.

Function prototype

void BIOSBoot(void);

Description
This function gracefully shutdowns REMBO and initiate a call to the software
interrupt 18h. On certain systems, a call to interrupt 18h asks the BIOS to boot on
the next bootable device. On other systems, it simply locks the boot process with a
message saying that no device is bootable.

282
4.6. GUI functions

MessageBox
MessageBox — Display a message and wait for user feedback
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str MessageBox(str title, str message, str buttons);

Description
MessageBox displays a modal dialog box, with the title and message specified as
arguments, and adds a choice of buttons for the user to acknowledge the message.
The buttons are specified as letters in the buttons argument:
Table 4-1. MessageBox buttons codes

y Yes
n No
o OK
c Cancel

MessageBox returns the letter corresponding to the button pressed by the user, or an
empty string if the window has been destroyed without clicking on a button.

See also
See also OpenNotice and OpenYesNo.

283
Logon
Logon — Let the user logon to an authentication server
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

bool Logon(void);

Description
Logon displays a logon dialog box, letting the user enter its username and password.
The function LogonUser is then called when the user press the Logon button.
Logon returns true if the authentication was successful, otherwise it returns false.

Screenshot

Figure 4-1. Logon dialog box

284
FileChooser
FileChooser — Open a file chooser dialog
Synopsis

Defined in
/plugins/admin.rbx

Function prototype

void FileChooser(str title, str defaultpath, str callback);

Description
FileChooser opens a dialog box for choosing a file, initially browsing the given
defaultpath. The user may either discard the dialog, or select a file and click
OK. In the latter case, the Rembo-C function whose name is given as callback
will be called with two string arguments, respectively the file path and name.

Example
void fc_callback(str path, str file)
{
Log("File "+file+" selected in path "+path+"<br>");
}
FileChooser("Choose a file","net://global/","fc_callback");

Screenshot

Figure 4-1. FileChooser dialog

285
OpenProgressBar
OpenProgressBar — Open a progress bar dialog
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void OpenProgressBar(str name, str info);

Description
OpenProgressBar opens an informative dialog box for reporting the progress of a
time-consuming process. No user interaction is expected in this dialog box.
If the global variable Settings.ProgressBar is set to false, the progress bar is not
displayed on the screen.
The name is used to uniquely identify the progress bar, in the case where several
progress bar are running simultaneously. the info text is displayed in the dialog
box to inform the user of the task just starting. This text can be changed
dynamically using SetProgressInfo.
When the progress bar is opened, the progress pointer is set to 0. To update the
progress to a value between 0 and 100 (progress completed), use SetProgressBar.
Use CloseProgressBar to close the progress dialog when the time-consuming
process is done.

Example
OpenProgressBar("test","This is a test");
for (int i=0;i<100;i++) {
SetProgressBar("test",i);
delay(50); // wait half a second
}
CloseProgressBar("test");

286
OpenProgressBar
Screenshot

Figure 4-1. Progress bar window

287
SetProgressBar
SetProgressBar — Update the progress indicator in a progress dialog
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void SetProgressBar(str name, int value);

Description
SetProgressBar changes the progress indicator in an open progress bar dialog. The
name must match the name of a previously open progress dialog, and the value
parameter must be a number between 0 and 100.

See also
See also OpenProgressBar.

288
SetProgressInfo
SetProgressInfo — Update the informative text in a progress dialog
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void SetProgressInfo(str name, str info);

Description
SetProgressInfo changes the informative text in an open progress bar dialog. The
name must match the name of a previously open progress dialog.

See also
See also OpenProgressBar.

289
CloseProgressBar
CloseProgressBar — Close progress dialog
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void CloseProgressBar(str name);

Description
This functions closes a progress bar previously opened with OpenProgressBar. The
parameter name must match the name of the open progress bar.

290
OpenMessage
OpenMessage — Open a generic message dialog
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var OpenMessage(str name, str msg);

Description
This function opens an informational window to display the message contained in
msg. This window has no button, and can only be closed by a call to CloseWindow.
OpenMessage returns a window structure describing the new window. The format of
this structure is the same as returned by OpenWindow.
The parameter name is the name of the window which will be created by
OpenMessage. You must use the same name in the call to CloseWindow in order to
close the message dialog.

Example
OpenMessage("mymsg","This is just a test...");
delay(500); // 5 seconds
CloseWindow("mymsg");

Screenshot

Figure 4-1. Sample OpenMessage window

291
OpenNotice
OpenNotice — Open a notice dialog
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var OpenNotice(str name, str msg);

Description
This function displays the notice message msg in a new window. The window is
created with an OK button closing the window when pressed.
OpenNotice returns a window structure describing the new window. The format of
this structure is the same as returned by OpenWindow.
The parameter name is the name of the window used by OpenNotice to create the
window. You can close a notice window with CloseWindow if the window still exists
(i.e. if the user has not clicked on the OK button).
You can use FileExists on the display: URL corresponding to the window to
determine whether the notice window is still alive or not. If you need a simple
modal message box, you can also use MessageBox instead.

Example
OpenNotice("mynot","This is a<br>multi-line notice.");
delay(500); // 5 seconds
// Close the window if it still exists
if (FileExists("display://mynot"))
CloseWindow("mynot");

292
OpenNotice
Screenshot

Figure 4-1. Sample OpenNotice window

See also
See also MessageBox.

293
OpenYesNo
OpenYesNo — Open a question dialog (yes/no dialog)
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var OpenYesNo(str name, str caption, str msg, str yes, str no);

Description
This function opens a window to display the message msg and to react to a yes/no
input from the user. The window is created with two buttons: YES and NO. If the user
clicks on YES, the Rembo-C statements stored in the string yes are executed. If the
user clicks on NO, the Rembo-C statements stored in the string no are executed.
OpenYesNo returns a window structure describing the new window. The format of
this structure is the same as returned by OpenWindow.
The window is automatically closed when the user clicks on any button. You do not
have to call CloseWindow to close the window.
The parameter name is the name used by OpenYesNo to create the window. You can
then access the window under this name, or use CloseWindow to close the window.
The caption is the window title, displayed in the blue title bar.
The strings yes and no can be empty. If a string is empty, nothing is performed
(outside closing the window) for the corresponding button.
If you need a yes/no modal dialog box, you can also use the alternate function
MessageBox instead.

Example
// OnYes handler
void OnYes(void) {
Log("You have clicked on YES<br>");
}
// OnNo handler
OnNo(void) {
Log("You have clicked on NO<br>");
}
var w=OpenYesNo("yesnowin","Yes/No test",

294
OpenYesNo
"This is <font color=blue>a test<font>",
"OnYes();","OnNo();");
w.resizable = false;

Screenshot

Figure 4-1. Sample OpenYesNo window

See also
See also MessageBox.

295
OpenMenu
OpenMenu — Open a graphical menu dialog
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var OpenMenu(str name, int xpos, int ypos, str header, var items);

Description
This function displays a menu of items on the screen. Each items can have its own
icon and description text.
Parameter name is the name used to create the window. You can use this name to
access the window or to close the window later.
xpos and ypos are the screen coordinates (in percents) of the upper left corner of
the menu. The height and width values are automatically computed by OpenMenu
based on the content of the menu.
header is the string inserted at the beginning of the window. It should contain a
<title> tag if you want to add a title bar to the menu. This header string could also
contain a <base href=...> tag to specify the base directory for the images
specified in the items parameter.
items is a two-dimensions array of size 3 by x, where x is the total number of
items to display in the menu. The three elements of each item are defined as follow:

• First element: a description string displayed on the right of the icon;


• Second element: the path to the icon to display for this item (string);
• Third element: the Rembo-C statement to execute when the user clicks on this
item.

OpenMenu returns a window structure describing the new window. The format of this
structure is the same as returned by OpenWindow.

Wizards menus are created with calls to OpenMenu.

296
OpenMenu
Example
OpenMenu("MainWiz", 25, 35,
"<title>Rembo Pro interactive tools</title>"
"<style>B {font-weight: normal; color: purple}</style>"
"<base href=’ram://1’>",
{
{"<br><br>Computer <b>settings</b>",
"keyb64.pcx", "CommonWizSet();" },
{ "<br><br><b>Floppy-disk</b> imaging and<br>"
"Ram-disk manipulations",
"fdmisc64.pcx", "CommonWizFD();" },
{ "<br><br><b>Hard-disk</b> partitioning,<br>"
"browsing and cloning",
"hd64.pcx", "InterWizHD();" },
{ "<br><br><b>Automated</b> boot<br>"
"configuration",
"robot64.pcx", "InterWizAuto();" },
{ "<br><br><b>Networking</b> tools",
"utp64.pcx", "CommonWizNet();" }
} );

Screenshot

Figure 4-1. Sample OpenMenu window

297
OpenEval
OpenEval — Open a Rembo-C evaluation dialog
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var OpenEval(str name, str header, str code, str footer, str
onclose);

Description
This function opens an evaluation window, containing the HTML code header,
followed by a textarea containing the Rembo-C source code code, followed by the
HTML code footer, followed by two buttons: Do It ! and Cancel.
If the user clicks on Do It !, the code contained in the textarea is executed. If the
user clicks on Cancel, the evaluation window is closed and nothing happens.
OpenEval returns a window structure describing the new window. The format of this
structure is the same as returned by OpenWindow.
The parameter name is the name used by OpenYesNo to create the window. You can
then access the window under this name, or use CloseWindow to close the window.
Since the Rembo-C code is displayed in a textarea, the user has the opportunity to
modify the statements directly before clicking on Do It !.
The Rembo-C statements contained in the onclose are executed when the
evaluation is finished (i.e. when the evaluation of the code in the textarea is
completed).

Example
str code = "delay(500);\n"
"Log(\"Hello world<br>\");";
str header = "<title>Evaluation test</title>"
"<body bgcolor=silver>"
" Code to execute:<br>";
OpenEval("eval",header,code,"","");

298
OpenEval
Screenshot

Figure 4-1. Sample OpenEval window

299
BuildFileSelect
BuildFileSelect — Build an HTML panel for choosing a file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str BuildFileSelect(str winname, str path, str mask, str


updatecallback);
void FileSelectUpdate(str winname, bool reset);

Description
The BuildFileSelect function returns a portion of HTML code that implements a
stand-alone file selection widget. The name of the window in which the widget is
put must be specified in parameter winname, as well as the path and file mask of
the files to list. Optionally, an updatecallback code can be specified, to be
executed each time the user selects a file (before validating its choice on the OK
button).
Once the widget is displayed on screen, you should call once the FileSelectUpdate
function with the reset parameter set to true, in order to initialize the file list.
The user selected path and filename can be finally obtained in the widgets fpath
and filename, for instance using the expression
StrChDir(fpath.value,filename.value)

The HTML code generated by these functions properly handles navigation keys for
mouse-less systems.

Example
MakeWindow("select",
"<title>My window</title>"
"<br>Select a file<br>"
+BuildFileSelect("select","disk://0:1","*.ini","")+
"<br>"
"<button onmouseup=’DoIt();’>OK</button>");
FileSelectUpdate("select",true);

300
BuildFileSelect

301
4.7. Applicative functions

FDisk
FDisk — Open a partition table editor window
Synopsis

Defined in
/plugins/admin.rbx

Function prototype

void FDisk(void);

Description
FDisk runs the interactive partition editor.

See also
See the manual page of GetPrimaryPartitions for a detailed discussion about
partitions.

Screenshot

Figure 4-1. FDisk tool

302
FileMan
FileMan — Open a file manager window
Synopsis

Defined in
/plugins/admin.rbx

Function prototype

void FileMan(str path);

Description
FileMan is a Windows-like file manager that lets you browse the content of any
partition or network filesystem.

Screenshot

Figure 4-1. FileMan Application

303
TextEdit
TextEdit — Open a text editor window
Synopsis

Defined in
/plugins/admin.rbx

Function prototype

void TextEdit(str filename);

Description
TextEdit is a simple text editor. You can edit text files and save changes by using
the menu on the upper left corner of the window.

Screenshot

Figure 4-1. TextEdit tool

304
OpenHTML
OpenHTML — Open an HTML browser window
Synopsis

Defined in
Built-in function.

Function prototype

void OpenHTML(str window, str path);

Description
OpenHTML opens a new window and displays the content of the given HTML file in
it. The window parameter is the name used to create the new window. The file
specified by path must be a file containing valid HTML tags.
OpenHTML uses the Browse function internally to parse the HTML file.
A window created with OpenHTML can be closed with a call to CloseWindow.

Example
OpenHTML("help","net://global/openhtml.html");

Screenshot

Figure 4-1. OpenHTML on this page

305
OpenHTML

306
4.8. User console control

AddToRootMenu
AddToRootMenu — Add an entry to the root menu
Synopsis

Defined in
Built-in function.

Function prototype

void AddToRootMenu(str label, str action);

Description
AddToRootMenu can be used to interactively add new items in the start menu. The
start menu is the icon on the bottom left corner of the screen. label is the text to
show in the start menu, and action is a valid script expression (a function call or
an assignment).

307
LockKeyboard
LockKeyboard — Disable the local keyboard
Synopsis

Defined in
Built-in function.

Function prototype

void LockKeyboard(bool locked);

Description
This function disables the keyboard if the parameter locked is true, and reenables
the keyboard if locked is false.

308
LockMouse
LockMouse — Disable the local mouse
Synopsis

Defined in
Built-in function.

Function prototype

void LockMouse(bool locked);

Description
This function disables the mouse device if the parameter locked is true, and
reenables the mouse device if locked is false.

309
LockScreen
LockScreen — Disable the local monitor
Synopsis

Defined in
Built-in function.

Function prototype

void LockScreen(bool locked);

Description
This function turns the screen off if the parameter locked is true, and reenables
the screen if the parameter locked is false.
LockScreen uses an Advanced Power Management call to turn the screen off/on.
You can determine whether APM is enabled on the computer with the variable
SystemInfo.APM. If the variable is true, APM is enabled.

310
AddRemoteConsole
AddRemoteConsole — Allow the connection of a remote console
Synopsis

Defined in
RConsole: /plugins/utils.rbx

AddRemoteConsole: Built-in functions

Function prototype

void RConsole(str host);


void AddRemoteConsole(str addr, int port);

Description
RConsole will start a remote console connection with the given remote host.
Parameter host must be a valid IP address, expressed as a string.
The remote console application should already be started on the remote console
host when running this command.
REMBO’s remote console feature makes it possible for a remote administrator to
control a REMBO host from its Windows desktop.
The remote console application can be found in the RConsole/ subdirectory of the
server installation directory.
AddRemoteConsole is the low-level primitive called by RConsole to initiate a remote
console connection. When called from RConsole, the port is set to 4021.

Example
RConsole("192.168.1.1");
AddRemoteConsole("192.168.1.1",4021);

311
KillRemoteConsole
KillRemoteConsole — Disconnect a remote console
Synopsis

Defined in
Built-in function.

Function prototype

void KillRemoteConsole(str ip, int port);

Description
This function stops a remote console connection. You must give the IP address of
the remote console host, and the port. If the connection was created with RConsole,
the port is 4021.

312
Chapter 5. Advanced Management Operations

This chapter describes functions that can be used to perform advanced pre-OS
management tasks. Some of them are only available in REMBO Pro and REMBO
Enterprise.

5.1. Advanced management operations by category


Table 5-1. Virtual and Loopback Images functions

CreateVirtualImage Create a new virtual disk image


LinkTree Recursively graft a directory tree to a
virtual image
UnlinkTree Recursively prune a directory tree to a
virtual image
FreeVirtualImage Dismiss a virtual disk image
CreateLoopback Create a new loopback device on a file
CloseLoopback Close loopback device

Table 5-2. Advanced imaging functions

OpenArchive Open a server archive for reading


CloseArchive Close a previously opened server
archive
OpenDiff Open a local archive for reading
CloseDiff Close a previously opened local archive
ArchiveType Read the first bytes of a file to detect if it
is an archive
OpenArchDevice Open an archive of any type
CloseArchDevice Close an archive opened with
OpenArchDevice
Synchronize Update a filesystem according to a
template image
SynchronizeEx Same as Synchronize, but return a
summary
TextDiff Create a complete list of differences
between two configurations
MakeDiffFromText Create a differential image from an
edited list of differences
ApplyDiff Apply a complete differential image to a
filesystem

313
Chapter 5. Advanced Management Operations
Table 5-3. Shared files repository manipulation functions

OpenShared Manually open the shared files


repository
MarkShared Count the shared space used by an
archive
StatShared Sum up the total space used by marked
shared files
SweepShared Garbage-collect the shared files
repository
CompactShared Free unused space preallocated for the
shared repository
CloseShared Manually close the shared files
repository
VerifyDLA Verify the consistence of the shared files
repository
GetSharedSize Get the total size of shared files required
by an archive

Table 5-4. Windows NT registry operations

OpenRegistry Open a Windows NT registry edition


session
CloseRegistry Close a Windows NT registry edition
session
NTSetPartition Change the NT system partition to be
used
NTDetect Detect the parameters of a NT system
NTCleanSignature Force the redetection of the disk
geometry by Windows
Win2KRegisterHDD Register a hard-drive into Win2k
registry
NTMapDrives Retrieve Windows drive mappings
Win2KRegisterParts Update Windows partition layout
Win2KChangeIPInfo Set Windows networking settings
manually
Win2KChangeNameServers Set Windows DNS servers
NTSetBootTimeout Change Windows NT boot delay
NTSetNetbiosName Change the NETBIOS name of the local
NT computer

314
Chapter 5. Advanced Management Operations

NTSetHostName Change the TCP/IP name of the local


NT computer
NTSetWinlogonDomain Change the logon name of the local NT
computer
NTChangeName Changes the name of the local NT
computer (shortcut)
NTInstallService Install a service on the local NT
computer
NTAutoLogon Change the auto logon information on
the local NT computer
NTJoinDomain Join a NT domain
GetSIDFromFile Extract a SID from a file
GetSIDFromRegistry Extract a SID from a registry file
ApplySID Set SID information on an opened
NTFS filesystem
GenerateSID Generate a new random SID based on an
existing SID
SIDToStr Get the textual representation of a
binary SID
PatchSIDReg Replace all SID occurences in a registry
file
PatchSID Replace all SID occurences in all
registry files

Table 5-5. INI file operations

NewIniFile Create an empty .ini file structure


ParseIniFile Parse an existing .ini file into memory
ParseIniFileDef Parse an .ini file, or create a new
structure
ParseIniString Parse an .ini content stored in a string
BuildIniFile Build an .ini content into a string for
saving
BuildUnquotedIniFile Build an .ini content, without quoting
values
TestIniValue Check for the existence of a value in an
.ini structure
GetIniValue Retrieve a value from an .ini structure
GetIniStruct Retrieve a section from an .ini structure
SetIniValue Update a value in an .ini structure

315
Chapter 5. Advanced Management Operations

SetIniStruct Update a section in an .ini structure


AddIniValue Add a new value in an .ini structure
AddIniSection Add a new section in an .ini structure
DiffIniFile Compare two .ini files and extract
differences
PatchIniFile Apply a set of modifications to an .ini
file

Table 5-6. Hardware and network detection

GetPnPCards Retrieve the array of PnP cards


GetPCICards Retrieve the array of PCI cards
PCIFindDevice Find a PCI device given its
vendor/device ID
PCIGetBusCount Get the total number of PCI buses
PCIGetSlot Get the PCI slot number for a given
device
PCIReadByte Read a byte in PCI registers
PCIReadWord Read a word in PCI registers
PCIReadDWord Read a double-word in PCI registers
PCIWriteByte Write a byte in PCI registers
PCIWriteWord Write a word in PCI registers
PCIWriteDWord Write a double-word in PCI registers
PortOutByte Output a byte in a I/O port
PortOutWord Output a word in a I/O port
PortInByte Input a byte in a I/O port
PortInWord Input a word in a I/O port
GetSystemDevices Retrieve the array of system devices
HWSignature Get the hardware signature
GetDMITables Retrieve a SMBIOS DMI table
GetDMIStrings Retrieve strings associated with a DMI
table
DMIProcessorInfo Retrieve DMI information about the
processor
DMISystemInfo Retrieve DMI information about the
processor
DMIMemoryInfo Retrieve DMI information about the
memory
DMIBIOSInfo Retrieve DMI information about the
BIOS

316
Chapter 5. Advanced Management Operations

DMIOnBoardDev Retrieve the list of on board devices


(DMI)
GetExtDiskInfo Get extended information about a BIOS
disk
IDEDetect Get information for all ATA (IDE) disks
Win2KRegisterBootDevice adds the PCI IDE controller to device
list
GetNICType Retrieve PCI information about the PXE
adapter
GetNICs Retrieve information about all network
adapters
ProbeServer Check if a Rembo server is online
RequestDHCPInfo Trigger a DHCP negotiation and create
DHCP variables
ReleaseDHCP Tell DHCP server that the address can
be reused
LoadUNDI Load the PXE UNDI layer into the
memory
SetIPInfo Activate an IP stack over PXE UNDI
layer
GetNetPass Retrieve NETFs password
GetServerInfo Retrieve server information

Table 5-7. Crypto and authentication functions

MD5Create Initialize a MD5 computation


MD5Update Update a MD5 computation
MD5Finish Terminate a MD5 computation
BlowFishEncrypt Crypt a binary block using Blowfish
BlowFishDecrypt Decrypt a binary block using Blowfish
AuthUser (AuthUser) Authenticate a user against a preset
domain
AuthUserEx (AuthUserEx) Authenticate a user against an arbitrary
domain

Table 5-8. TCP connectivity functions

TCPConnect Initiate a TCP connection


TCPRead Read bytes from a TCP connection
TCPWrite Send bytes to a TCP peer
TCPClose Close a TCP connection

317
Chapter 5. Advanced Management Operations

SendMail Send a mail to an arbitrary email address

SQLOpen Open an ODBC session with a database


server
SQLOpenEx Open an ODBC session with extra
parameters
SQLQuery Execute a SQL query on an open ODBC
session
SQLClose Close an ODBC session
SQLQuickQuery Execute a SQL query

Table 5-9. Other system primitives

DeviceBlank Blank-erase the content of a device


DeviceClean Quick-format a device with the default
filesystem
DeviceCleanEx Quick-format a device according to
filesystem-specific parameters
DeviceCleanForce Quick-format a device with a specified
filesystem
DevicePreAdapt Prepare to temporarily resize a partition
to a smaller size ;
DeviceAdapt Temporarily resize filesystem structures
to a new partition size
DeviceClose Flush and release ressources associated
to an open filesystem
DeviceCheck Detect and optionally fix filesystem
corruptions
DeviceSetDirty Change the dirty flag of a device
DeviceBoot Boot from a specified device
FileBoot Boot using the content of a file
DeviceInfo Gather general information about a
device
DeviceAllocInfo Gather allocation information about a
device
DeviceGetInfo Collect filesystem-specific parameters
about a device
DeviceGetFsType Return the partition type required by a
given device

318
Chapter 5. Advanced Management Operations

WriteOfflineCode Write an offline mode Rembo boot


sector to a device
DevReadBootSects Read boot sectors on an arbitrary
filesystem
DevWriteBootSects Write boot sectors on an arbitrary
filesystem
DevReadLabel Read the label associated with a
filesystem
DevWriteLabel Modify the label associated with a
filesystem
DevReadUUID Read the UUID value associated with a
filesystem
DevWriteUUID Modify the UUID value associated with
a filesystem
InitDownload Setup a multicast download process
InitUDownload Setup an unicast download process
MoreDownload Continue a download process
InfoDownload Get information about the progress of a
download
DownloadResult Retrieve the result of a memory
download
InitBatchTransfer Setup a multiple file transfer process
AddToBatchTransfer Add a file to a multiple file transfer
process
MoreBatchTransfer Continue a multiple file transfer process
InfoBatchTransfer Get information about the progress of a
transfer process
InitSynchro Setup a filesystem synchronization
MoreSynchro Continue a filesystem synchronization
InfoSynchro Get informations about the progress of a
filesystem synchronization
SynchroStats Get summary informations about a
filesystem synchronization
ApplyTextDiff Apply an edited textual difference to a
virtual image
InitRemboFloppy Setup cache-to-floppy cloning process
InitRemboCDRom Setup cache-to-cdrom cloning process
MoreRemboClone Continue a cache cloning process
BuildFileIndex Build an index of server files

319
GUnzip Uncompress a GZIP binary buffer

5.2. Virtual and Loopback Images functions

CreateVirtualImage
CreateVirtualImage — Create a new virtual disk image
Synopsis

Defined in
Built-in function.

Function prototype

void CreateVirtualImage(str alias, str basepath);

Description
CreateVirtualImage allocates memory-based virtual filesystem that you can use as
a workbench to make a real filesystem look different from what it is. The alias is
the name to use as root device when accessing the virtual filesystem, and the
basepath is the path of the filesystem to clone.
You can access a virtual image with the path link://xxx where xxx is the alias you
choosed when creating the virtual image.
To edit the virtual filesystem, use the functions LinkTree and UnlinkTree to
efficiently graft and prune the filesystem directory tree. In addition, you can use
most of the usual file manipulation functions, except that the virtual filesystem can
store no file on its own (files must be stored on another filesystem and linked using
LinkTree).

Virtual images can be used when creating a disk image to remove unwanted files
without actually removing these files from the source hard disk. On restoration,
virtual images can be used to merge a disk image with another disk image
(differential image).
You should deallocate the virtual image when you do not need it any more, using
the function FreeVirtualImage.

320
CreateVirtualImage
See also
See also LinkTree, UnlinkTree, FreeVirtualImage and Link URL type.

321
LinkTree
LinkTree — Recursively graft a directory tree to a virtual image
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void LinkTree(str linkpath, str target);

Description
LinkTree is intended to be used on virtual images created using
CreateVirtualImage. It creates a link at the path given by linkpath to the file or
directory tree given by target.
If linkpath and target are both existing directories, the content of the two
directories will be merged into linkpath. Otherwise, any existing link at
linkpath is replaced by a link to the target.
LinkTree is an alias for FileLink.

See also
See also UnlinkTree to unlink a file or a full directory tree.

322
UnlinkTree
UnlinkTree — Recursively prune a directory tree to a virtual image
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void UnlinkTree(str linkpath);

Description
UnlinkTree is intended to be used on virtual images created using
CreateVirtualImage. It destroys the given link (even if the link was not explicitely
created), effectively pruning the whole directory tree.
UnlinkTree is an alias for FileUnlink.

See also
See also LinkTree to graft a file or a full directory tree.

323
FreeVirtualImage
FreeVirtualImage — Dismiss a virtual disk image
Synopsis

Defined in
Built-in function.

Function prototype

void FreeVirtualImage(str alias);

Description
FreeVirtualImage destroy a virtual disk image previously allocated with
CreateVirtualImage. All changes made to the virtual image are permanently lost.

324
CreateLoopback
CreateLoopback — Create a new loopback device on a file
Synopsis

Defined in
Built-in function.

Function prototype

void CreateLoopback(int loopnum, str loopfile, int ofs, int len);

Description
This function creates a new loopback device on existing file loopfile. The
parameter loopnum is the loop device index (starting at 0).
Parameters ofs and len can be used to use a subset of the file only. Parameter
ofs specifies the starting offset in bytes in the file loopfile, while len is the
number of bytes to access in the file. If len is 0, the loopback device is setup to use
all the bytes until the end of the file.
A loop device is an emulation of a block device (i.e. a floppy) on a regular file. The
device can be used as a ramdisk, or a floppy, but all read and writes are actually
performed on the underlying file (the loop file).
Once created, the loop device can be access with a loop://x where x is the index of
the loop device.

Example
CreateLoopback(0,"net://global/loopfile",0,0);
DeviceCleanForce("loop://0","FAT12");
ViewDir("loop://0");

/* Open the TEMPFS image on a bootable Rembo CD Image */


CreateLoopback(0,"cache://global/isoimage",49152,0);
ViewDir("loop://0");

325
CloseLoopback
CloseLoopback — Close loopback device
Synopsis

Defined in
Built-in function.

Function prototype

void CloseLoopback(int loopnum);

Description
This function closes a loopback device and release all resources associated with the
looback device.
Closing a loopback device is important if you want to make sure that all writes to
the device have been written to the file (e.g. before rebooting).

326
5.3. Advanced imaging functions

OpenArchive
OpenArchive — Open a server archive for reading
Synopsis

Defined in
Built-in function.

Function prototype

void OpenArchive(str alias, str path);

Description
OpenArchive opens and mount the disk image archive given by the parameter path
for reading. The content of the archive can then be accessed (read-only) through
Arch URLs (arch://alias). The alias will be the name of the root device. See
the description of Arch URLs for more details.
This function can only read archives created on the server (using CreateDiskImage
or using Synchronize with the destination path on the server).

See also
See also Arch URLs and Synchronize.

327
CloseArchive
CloseArchive — Close a previously opened server archive
Synopsis

Defined in
Built-in function.

Function prototype

void CloseArchive(str alias);

Description
CloseArchive closes an archive file previously open using OpenArchive and
releases all associated ressources. See the description of Arch URLs for more
details.
As long as the archive is open, the file containing the archive is marked busy and
cannot be access by other threads/functions. You must close an archive to release
the underlying file.

See also
See also Arch URLs.

328
OpenDiff
OpenDiff — Open a local archive for reading
Synopsis

Defined in
Built-in function.

Function prototype

void OpenDiff(str alias, str path);

Description
OpenDiff opens and mount the disk image archive given by the parameter path for
reading. The content of the archive can then be accessed (read-only) through Diff
URLs (diff://alias). The alias will be the name of the root device. See the
description of Diff URLs for more details.
This function can only read Diff archives created locally (using Synchronize with
the destination path on the local hard-disk).

See also
See also Diff URLs and Synchronize.

329
CloseDiff
CloseDiff — Close a previously opened local archive
Synopsis

Defined in
Built-in function.

Function prototype

void CloseDiff(str alias);

Description
CloseDiff closes an archive file previously open using OpenDiff and releases all
associated ressources. See the description of Diff URLs for more details.
As long as the archive is open, the file containing the archive is marked busy and
cannot be access by other threads/functions. You must close an archive to release
the underlying file.

See also
See also Diff URLs.

330
ArchiveType
ArchiveType — Read the first bytes of a file to detect if it is an archive
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str ArchiveType(str archpath);

Description
This function reads the magic number at the beginning of the file pointed by
archpath to detect if it is a server archive (that can be accessed using
OpenArchive), a local archive (that can be accessed using OpenDiff) or any other
type of file. The function will return a string, respectively "arch", "diff" or
"file".

Example
int totalsizekb = (FileStat(netfile).size+1023) / 1024;
if(ArchiveType(netfile) != "file")
totalsizekb += GetSharedSize(netfile);

See also
See also OpenArchDevice.

331
OpenArchDevice
OpenArchDevice — Open an archive of any type
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str OpenArchDevice(str alias, str path);

Description
OpenArchDevice opens and mount the server or disk image archive given by the
parameter path for reading, and returns the root URL that can be used to access its
content (read-only). The alias will be used to build the name of the root device.
This function automatically differentiates arch devices and diff devices. To access
an individual file within the archive, use the StrChDir function, with the URL
returned by OpenArchDevice as first argument, and the relative path of the desired
file as second argument.

Example
str testroot = OpenArchDevice("cache://global/test.img");
str testfile = StrChDir(testroot, "data/sample1");
CopyFile(testfile, "disk://0:1");
CloseArchDevice(testroot);

See also
See also ArchiveType, CloseArchDevice and StrChDir.

332
CloseArchDevice
CloseArchDevice — Close an archive opened with OpenArchDevice
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void CloseArchDevice(str archurl);

Description
CloseArchDevice closes any type of archive file previously open using
OpenArchDevice and releases all associated ressources. The parameter archurl is
not the alias name given to the archive, but the whole URL returned by
OpenArchDevice when opening the archive.

As long as an archive is open, the file containing the archive is marked busy and
cannot be access by other threads/functions. You must close an archive to release
the underlying file.

Example
str testroot = OpenArchDevice("cache://global/test.img");
str testfile = StrChDir(testroot, "data/sample1");
CopyFile(testfile, "disk://0:1");
CloseArchDevice(testroot);

See also
See also ArchiveType, OpenArchDevice and StrChDir.

333
Synchronize
Synchronize — Update a filesystem according to a template image
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void Synchronize(str source, str target, str options);

Description
Synchronize is the main function of REMBO as far as disk imaging is concerned. It
updates the content of the target filesystem according to the content of the
source filesystem. This can be used for creating disk image archives as well as for
restoring the content of an archive to the disk. The options specifies how the
comparison is to be made, and optionally the name of an (incremental) archive file
where to store the difference between the source and the target filesystems (see
below).
If the destination parameter is a file referenced by a net: or cache: URL (a remote
file), an image of the source filesystem will be created in this file (disk imaging).
If the source parameter is a remote file, then Synchronize will restore the content of
this disk image into the destination filesystem.
By default, Synchronize will compare the timestamps of all the files existing in
both the source and the destination and will build a list of files to update (modified
files). In addition, it will consider all files existing in source but not in destination as
new files (files to add) and all files existing only in the destination as old files (files
to remove). If used in default mode, Synchronize will not backup the boot sector of
the source partition.
The third parameter can be used to modify the default behaviour of Synchronize.
This third parameter is a string made of a combination of the following operands:

• +: do not remove files existing in destination but not source (only add new files);
• =: do not remove existing in destination nor add files (only update existing files);
• -: this special mode is used when the source is an archive containing negative
entries (files to delete). Option - will tell Synchronize to delete all the files for

334
Synchronize
which the archive has a matching delete entry. This is useful for restoring registry
patches (where deleted entries can be very important);
• ?: do not use timestamps to compare files, but compute MD5 digest on each file
to compare the content of the files as well (more secure than the default
behaviour);
• !: do not compare files, and make the assumption that every file has changed (the
most secure beahviour: all files will be restored/backuped);
• b: backup/restore the boot sector;
• x: do not backup or restore file attributes. File attributes are security descriptors
for NTFS and registry filesystem, and file modes (readable file, writeable file, ...)
for other filesystems. File attributes are backuped and restored by default. You
may want to prevent REMBO to backup and restore file attributes if you are
creating an archive containing NT security identifiers, and you know that the
archive will be restored on a computer using a different security identifier as the
reference computer;
• 0-9: compression level of the resulting image, if relevant;
• o: create an old monolithic image, without using the new shared repository, as it
was previously done in pre-2.0 releases. Note that if you decide to use the old
format to store a NTFS disk image, you will not be able to benefit of the new
NTFS inodes and streams preservation features. Note also that you cannot use a
destination path based on a cache:// URL with this attribute (use net://
instead).
• (logfile): full path of a file to store the list of files that differ between the source
and the destination. Files that have been added in the destination are prefixed
with a plus, files that have been removed are prefixed with a minus, and files that
are different are prefixed with a number sign;
• >filename: store the difference between the source and the destination in another
archive, instead of directly applying the modifications to the destination (used to
create incremental images based on a reference image). When no filename is
given, the difference is simply discarded (used to create a log file of differences,
without storing the content of the differences).

Examples

Create a disk image of the first partition and store this image in the file
net://global/diskimage (images must be created on the server). Boot sectors are
backuped.
Synchronize("disk://0:1/","net://global/diskimage","b");

335
Synchronize

Restore the image on a fresh partition (HDClean is run to clean the partition before
restoring the image).
HDClean(0,1);
Synchronize("cache://global/diskimage","disk://0:1/","b");

Restore the image on a existing partition (only restore modified files). This mode is
very useful in situations where the image must be restored once a day or at every
boot.
Synchronize("cache://global/diskimage","disk://0:1/","b");

In a secure environment (public internet cafés or student workstations), it is advised


to use MD5 comparison to make sure that every modified file is restored. The
default mode of Synchronize may miss modified files if timestamps have not been
modified. The MD5 comparison mode is slower than the default (timestamps) mode
because it requires REMBO to read the content of the destination files for
comparison with the MD5 digests stored in the archive.
Synchronize("cache://global/diskimage","disk://0:1/","b?");

Restore the image on a existing partition and avoid deleting existing files. This
mode can be used to restore the core of an operating system without deleting files
added by the user.
Synchronize("cache://global/diskimage","disk://0:1/","b+");

Compare the content of the disk with a reference image, and store the list of
added/removes/modified files in a log file.
Synchronize("cache://global/diskimage","disk://0:1/",
"(cache://global/changelog)>");

Create an incremental archive (a difference between the content of a disk partition


and an image) in the file net://global/diskdiff. You can use this mode to create
differential archives: you first create an archive containing a reference operating
system installation, and then you create a differential archive for each kind of
hardware you want to support (the differential archive will contain only a few files).
Then, use the VirtualImage scripting functions to build a virtual image made of the
reference image and the differential image adapted to the current hardware.

336
Synchronize
Synchronize("disk://0:1/",
"cache://global/diskimage",
"b>net://global/diskdiff");

Create an archive (a disk image) and then browse the archive with the File Manager.
Synchronize("disk://0:1/","net://global/diskimage","b");
OpenArchive("archivetest","cache://global/diskimage");
FileMan("arch://archivetest/");

See also
See also SynchronizeEx, CreateVirtualImage, LinkTree, UnlinkTree,
FreeVirtualImage, OpenArchive, and CloseArchive.

337
SynchronizeEx
SynchronizeEx — Same as Synchronize, but return a summary
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var SynchronizeEx(str source, str target, str options);

Description
SynchronizeEx behaves exactly like Synchronize, but returns in addition a
structure summarizing the operation performed by the synchronize operation. The
structure members are:

• skipped: the number of files that were skipped by the operation because they
were unreadable;
• added: the number of files added to the destination filesystem;
• deleted: the number of files removed from the destination filesystem;
• modified: the number of files updated on the destination filesystem.

See also
See also Synchronize.

338
TextDiff
TextDiff — Create a complete list of differences between two configurations
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var TextDiff(str diskpath, str refimage, str textdiff, bool nt);

Description
TextDiff, MakeDiffFromText and ApplyDiff are three functions that together
allow the creation of clean differential snapshot images, through a manual review of
the changes to be included in the image.
TextDiff compares the files under diskpath with the content of the archive
pointed by refimage and creates an explicit list of all differences into the file
textdiff.
The list of differences is split in several sections. The first section lists all files
modified, added or removed. If the parameter nt is set to true, there is one
additional section for each registry hive changed, with individual key changes listed
explicitely. Additionally, changes to each .ini file are also listed in a separate section.
The textual difference log is typically reviewed and edited manually to remove any
pseudo-difference that is not relevant to the snapshot image beeing created. After
manual edition, the differential image itself can be created using
MakeDiffFromText.

Note that creating differential images including Windows registry changes might be
a very memory-intensive operation. In some cases, it may be safer to reboot between
the creation of the incremental log and the creation of the differential image itself.

See also
See also MakeDiffFromText, ApplyDiff.

339
MakeDiffFromText
MakeDiffFromText — Create a differential image from an edited list of
differences
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var MakeDiffFromText(str diskpath, str refimage, str textdiff, str


diffpath, bool nt);

Description
TextDiff, MakeDiffFromText and ApplyDiff are three functions that together
allow the creation of clean differential snapshot images, through a manual review of
the changes to be included in the image.
MakeDiffFromText creates an incremental snapshot image of the differences
between the files at diskpath and the reference image pointed by refimage,
taking into account only the changes recorded in the incremental log pointed by
textdiff. The resulting image is stored into one or more files, with diffpath
serving as basename and using various extensions to store all components of the
incremental image (files, ini files...). If the parameter nt is set to true, registry files
are handled in details, with separate incremental images.
Prior to calling this function, you should create an incremental log using TextDiff.
Once you have your incremental image ready, you can apply it on a filesystem using
ApplyDiff.

Note that creating differential images including Windows registry changes might be
a very memory-intensive operation. In some cases, it may be safer to reboot between
the creation of the incremental log and the creation of the differential image itself.

See also
See also TextDiff, ApplyDiff.

340
ApplyDiff
ApplyDiff — Apply a complete differential image to a filesystem
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var ApplyDiff(str diffpath, str diskpath, bool nt);

Description
TextDiff, MakeDiffFromText and ApplyDiff are three functions that together
allow the creation of clean differential snapshot images, through a manual review of
the changes to be included in the image.
ApplyDiff opens the various components of the incremental image pointed by
diffimage (usually created by MakeDiffFromText) and performs all the changes
on the base path specified in diskpath.
If the parameter nt is set to true, registry files are also updated by applying the
incremental changes recorded in the image.

See also
See also MakeDiffFromText, TextDiff.

341
5.4. Shared files repository manipulation functions

OpenShared
OpenShared — Manually open the shared files repository
Synopsis

Defined in
Built-in function.

Function prototype

var OpenShared(str devicePath, bool clearMarks);

Description
The function OpenShared opens a shared files repository to manually perform
maintenance operations, such as accounting and garbage collection.
The devicePath parameter is not directly the path of the shared files repository,
but the base path relative to which Settings.SharedPath will be applied to
determine the path of the local repository. For instance, assuming that
Settings.SharedPath has the default value "/shared" and that devicePath is
set to disk://0:-1/default, the repository will be opened in
disk://0:-1/shared.

If the clearMarks parameter is set to true, the use count of every file will be
cleared to zero while opening the repository. This is useful before running a
mark-and-sweep garbage collection. Opening the repository without clearing the
use counts may already give a good estimation of the number of files in the
repository, as use counts are automatically incremented when adding files to the
repository.

You should always close the shared files repository using CloseShared when
you have finished working on it, or some data may be lost. When reopening an
repository that has not been properly flushed, an extensive verification will
automatically be performed, and all incomplete or damaged structures will be
cleared.

Example
// Open the shared files repository

342
OpenShared
var shared = OpenShared("disk://0:-1",true);

// Show the files used by the two first images


LogVar(MarkShared(shared, "disk://0:-1/test1.img"));
LogVar(MarkShared(shared, "disk://0:-1/test2.img"));

// Show the total allocated space for the two images


LogVar(StatShared(shared));

// Show the files used by the 3rd image


LogVar(MarkShared(shared, "disk://0:-1/test3.img"));

// remove all files not required by any archives


LogVar(SweepShared(shared));

// close the repository


CloseShared(shared);

See also
See also MarkShared, StatShared, SweepShared, CompactShared and CloseShared.

343
MarkShared
MarkShared — Count the shared space used by an archive
Synopsis

Defined in
Built-in function.

Function prototype

var MarkShared(var shared, str archive);

Description
The function MarkShared scans the shared archive whose filename is given as
argument archive, and increments the usage count in the shared files repository
for all files used by the archive.
The functions returns a structure describing the count and status of the files
scanned, using the following members:

• newFiles: this is the number of files that have been marked while processing the
archive and that were not marked before;
• newSizeKB: this is the total size (in kilobytes) of all files that have been marked
while processing the archive and that were not marked before;
• newStorageKB: this is the total storage space (in kilobytes) used to store files
that have been marked while processing the archive, and that were not marked
before. It can be thought as the space actually needed to store the archive using
the shared storage mechanism, taking into account both the compression and the
unique storage of duplicate files;
• reuseFiles: this is the number of files that have been marked while processing the
archive but that were already marked by a previous archive;
• reuseSizeKB: this is the total size (in kilobytes) of all files that have been marked
while processing the archive but that were already marked by a previous archive;
• reuseStorageKB: this is the total storage space (in kilobytes) that was spared
thanks to the fact that duplicate files are only stored once in the repository;
• missingFiles: this is the number of files referenced by the archive that have not
been found in the shared files repository. If this number is greater than zero, it
means that the archive cannot be completely restored using the shared repository
(some data is missing);

344
MarkShared
• missingSizeKB: this is the total size (in kilobytes) of all files that are referenced
by the archive but have not been found in the shared repository. If the missing
files are to be downloaded or copied from a foreign source, this gives an estimate
of the amount of data that needs to be transfered (without taking into account the
possible compression, determined by the source).

In order to get a summary of such values accross a set of archives, use StatShared.

Example
// Open the shared files repository
var shared = OpenShared("disk://0:-1",true);

// Show the files used by the two first images


LogVar(MarkShared(shared, "disk://0:-1/test1.img"));
LogVar(MarkShared(shared, "disk://0:-1/test2.img"));

// Show the total allocated space for the two images


LogVar(StatShared(shared));

// Show the files used by the 3rd image


LogVar(MarkShared(shared, "disk://0:-1/test3.img"));

// remove all files not required by any archives


LogVar(SweepShared(shared));

// close the repository


CloseShared(shared);

See also
See also OpenShared, StatShared, SweepShared, CompactShared and CloseShared.

345
StatShared
StatShared — Sum up the total space used by marked shared files
Synopsis

Defined in
Built-in function.

Function prototype

var StatShared(var shared);

Description
The function StatShared scans the whole shared repository and sums up various
sizes to summarize the use of allocated disk space. The classification of files among
the various categories (used files, orphan files) is mostly based on the usage count
associated to each entry, which can be explicitely updated using the MarkShared
function. function.
This function returns a structure describing the total count and storage space needed
by used, missing and unused (orphan) files in the repository (as well as a few other
values):

• usedFiles: this is the number of files stored in the shared files repository and
actually used by one or more archives;
• usedSizeKB: this is the total size (in kilobytes) of all files stored in the shared
files repository and actually used by one or more archives;
• usedStorageKB: this is the total storage space (in kilobytes) used to store files in
the shared files repository that are actually used by one or more archives. It can
be thought as the space actually needed to store all archives using the shared
storage mechanism, taking into account both the compression and the unique
storage of duplicate files;
• missingFiles: this is the number of files that have been searched for in the shared
repository but that are missing or that are not completely stored because a
transfer was interrupted;
• missingSizeKB: this is the total size (in kilobytes) of all files that have been
searched for in the shared repository but that are missing or that are not
completely stored because a transfer was interrupted;

346
StatShared
• missingStorageKB: this is the storage space (in kilobytes) used to store all partial
entries for files that are missing or incomplete because a transfer was interrupted.
This space can be recovered by calling the SweepShared function;
• orphanFiles: this is the number of files stored in the repository but not
referenced by any archive (or at least not by any archive marked since the last
time the usage counts were cleared);
• orphanSizeKB: this is the total size (in kilobytes) of all files that are stored in the
shared repository but not anymore used by any archive (or at least not by any
archive marked since the last time the usage counts were cleared);
• orphanStorageKB: this is the storage space (in kilobytes) wasted to store all files
that are not anymore used by any archive (or at least not by any archive marked
since the last time the usage counts were cleared). This space can be recovered by
calling the SweepShared function;
• preallocKB: this is the storage space allocated by the shared files repository to
store internal structures and reserved for future files. It should roughly be equal to
the difference between the sum of all shared repository pool files and indexes and
the sum of all storaged spaced described above.
• recoverableKB: this is an estimate of the storage space that could be recovered
by sweeping from the repository all incomplete and orphan entries, using the
SweepShared function;

• hardrecoverableKB: this is an estimate of the disk space that could be recovered


by sweeping from the repository all incomplete and orphan entries, and
compacting all pool files to their shortest possible size, using the CompactShared
function;

Example
// Open the shared files repository
var shared = OpenShared("disk://0:-1",true);

// Show the files used by the two first images


LogVar(MarkShared(shared, "disk://0:-1/test1.img"));
LogVar(MarkShared(shared, "disk://0:-1/test2.img"));

// Show the total allocated space for the two images


LogVar(StatShared(shared));

// Show the files used by the 3rd image


LogVar(MarkShared(shared, "disk://0:-1/test3.img"));

// remove all files not required by any archives


LogVar(SweepShared(shared));

347
StatShared

// close the repository


CloseShared(shared);

See also
See also OpenShared, MarkShared, SweepShared, CompactShared and CloseShared.

348
SweepShared
SweepShared — Garbage-collect the shared files repository
Synopsis

Defined in
Built-in function.

Function prototype

var SweepShared(var shared);

Description
The SweepShared function scans all files in the shared files repository, and remove
all useless entries (incomplete files and unreferenced entries). The recovered space
is kept in the preallocated pool files, except if a pool file becomes completely empty
as the result of the sweep mechanism, in which case it will be deleted and the disk
space will be freed.
This function returns the same information structure as StatShared. The
information refers to the state of the shared files repository before the sweep
operation.

Example
// Open the shared files repository
var shared = OpenShared("disk://0:-1",true);

// Show the files used by the two first images


LogVar(MarkShared(shared, "disk://0:-1/test1.img"));
LogVar(MarkShared(shared, "disk://0:-1/test2.img"));

// Show the total allocated space for the two images


LogVar(StatShared(shared));

// Show the files used by the 3rd image


LogVar(MarkShared(shared, "disk://0:-1/test3.img"));

// remove all files not required by any archives


LogVar(SweepShared(shared));

// close the repository


CloseShared(shared);

349
SweepShared

See also
See also OpenShared, MarkShared, StatShared, CompactShared and CloseShared.

350
CompactShared
CompactShared — Free unused space preallocated for the shared repository
Synopsis

Defined in
Built-in function.

Function prototype

var CompactShared(var shared);

Description
The CompactShared function scans all files in the shared files repository, and
remove all useless entries (incomplete files and unreferenced entries). In addition,
the every pool file is truncated to its minimum size for the remaining content, and
all possible disk space is freed.
This function returns the same information structure as StatShared. The
information refers to the state of the shared files repository before the compaction.

Contrarily to the natural cleaning mechanism performed by SweepShared, the


truncation done by CompactShared should not be used when not really needed,
as it will lead to disk fragmentation and reduced performances when used
often.

Example
// Open the shared files repository
var shared = OpenShared("disk://0:-1",true);

// Mark all used files


MarkShared(shared, "disk://0:-1/test1.img");
MarkShared(shared, "disk://0:-1/test2.img");
MarkShared(shared, "disk://0:-1/test3.img");

// Truncate the repository to its minimal size


LogVar(CompactShared(shared));

// Close the repository


CloseShared(shared);

351
CompactShared
See also
See also OpenShared, MarkShared, StatShared, SweepShared and CloseShared.

352
CloseShared
CloseShared — Manually close the shared files repository
Synopsis

Defined in
Built-in function.

Function prototype

void CloseShared(var shared);

Description
The CloseShared function closes the shared files repository previously opened
using OpenShared. It is important to always close a shared files repository in order
to flush all index structures.

See also
See also OpenShared.

353
VerifyDLA
VerifyDLA — Verify the consistence of the shared files repository
Synopsis

Defined in
Built-in function.

Function prototype

void VerifyDLA(str devicePath, bool applyFix, bool logErrors);

Description
The VerifyDLA function explicitely performs an extensive verification on all
internal structures of a shared files repository, to ensure that all further accesses will
not fail, even if the repository has been incorrectly flushed or badly corrupted. This
check is automatically done when using a shared files repository that has not been
cleanly flushed when used for the last time.
The devicePath parameter is not directly the path of the shared files repository,
but the base path relative to which Settings.SharedPath will be applied to
determine the path of the local repository. For instance, assuming that
Settings.SharedPath has the default value "/shared" and that devicePath is
set to disk://0:-1/default, the repository will be opened in
disk://0:-1/shared.

If the parameter applyFix is set to true, any incorrect structure will be fixed by
deleting the corresponding entry (possibly leading to the deletion of data).
Otherwise, the repository is checked but left unchanged.
If the parameter logErrors is set to true, a detailled error log will be generated
on the console, describing the fixes done (or to be done).

This extensive verification can take a significant time, depending on the


number of files stored in the shared files repository.

Example
VerifyShared("disk://0:-1", true, false);

354
VerifyDLA
See also
See also OpenShared.

355
GetSharedSize
GetSharedSize — Get the total size of shared files required by an archive
Synopsis

Defined in
Built-in function.

Function prototype

int GetSharedSize(str path);

Description
The GetSharedSize function asks the server to compute the total size (in kilobytes)
of all shared files required by the archive pointed by path. This can be used for
instance to estimate the size of the cache partition needed to store the specified
archive. If the archive is not using the (new) shared format, the function returns
zero.
The resulting value is computed only once by the server, and then cached if further
clients request it.
The sum is computed using the current size on disk of every file in the archive. First
consequence: the compressed size is reported; second consequence: the result is an
over-estimate because the size is added for each occurence of the file, although the
server stores it only once.

Example
int totalsizekb = (FileStat(netfile).size+1023) / 1024;
if(ArchiveType(netfile) != "file")
totalsizekb += GetSharedSize(netfile);

See also
See also MarkShared.

356
5.5. Windows NT registry operations

OpenRegistry
OpenRegistry — Open a Windows NT registry edition session
Synopsis

Defined in
Built-in function.

Function prototype

void OpenRegistry(str regname, str path);

Description
OpenRegistryopens and prepares a Windows NT registry for access through Reg
URLs (reg://regname). The regname will be the name of the root device. See the
Reg URL page for more details.
In Windows NT, registry files are located in \winnt\system32\config and are
called software, security, system, default and sam.
If you use the Pro/Enterprise wizards, there is an option to browse the registry as
one virtual image built by merging the five registry files together with the same
names as in Windows NT (LOCAL_MACHINE, ...).
When you do not need to perform file operations on a registry, you must close it
with CloseRegistry to make sure that all data is flushed to the disk.
See the manual page for reg: urls for a description of the registry file types
supported by REMBO

Example
OpenRegistry("ntsys","disk://0:1/winnt/system32/config/system");
ViewDir("reg://ntsys");

357
CloseRegistry
CloseRegistry — Close a Windows NT registry edition session
Synopsis

Defined in
Built-in function.

Function prototype

void CloseRegistry(str alias);

Description
CloseRegistry commits changes to the registry, and release all associated
resources (in particular it closes the registry file). Do not forget to close the registry
after using it to avoid a corruption of your registry files.

358
NTSetPartition
NTSetPartition — Change the NT system partition to be used
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void NTSetPartition(int partition);

Description
This function should be used to set the partition on which Windows NT or Windows
2000 has been restored if this is not the same partition number as on the reference
computer (i.e. the computer used when creating the image). You can also use this
function to set the NTLocation variable to the proper value if Windows NT/2000 is
not installed on the first partition.
This function modifies the file boot.ini in the root directory of the Windows NT
system partition to match the value given in parameter. This may not be able to
change boot.ini if you are using SCSI drives.

Example
// Restore Windows NT on 2nd partition
HDClean(0,2);
Synchronize("cache://global/ntimage","disk://0:2","b");
// Set system partition
NTSetPartition(2);
// Detect Windows NT version
if(NTDetect())
Printf("Windows %s installed in \\%s", NTType, NTSystemRoot)
// Change hostname
NTChangeName("REMBO");

359
NTDetect
NTDetect — Detect the parameters of a NT system
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

bool NTDetect(void);

Description
This function should be used to determine the parameters of a Windows NT/2000
installation, after NTSetPartition has been called to select a partition.
The function answers true if the Windows installation has been properly verified
(registry files have been found and the version is known) and false otherwise.
This function sets the following global variables:

• NTType: a string identifying the Windows version.


• NTSytemRoot: the directory name where the Windows system is installed
(typically winnt or windows.

Example
// Restore Windows NT on 2nd partition
HDClean(0,2);
Synchronize("cache://global/ntimage","disk://0:2","b");
// Set system partition
NTSetPartition(2);
// Detect Windows NT version
if(NTDetect())
Printf("Windows %s installed in \\%s", NTType, NTSystemRoot)
// Change hostname
NTChangeName("REMBO");

360
NTCleanSignature
NTCleanSignature — Force the redetection of the disk geometry by Windows
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void NTCleanSignature(int disk);

Description
This function rewrites a double-word in the master boot record (MBR) of the
specified disk to force Windows NT (2000) to reread its geometry and partition
table. Otherwise, Windows will use the information cached in the registry, that may
be outdated after a cloning operation.
Note that if this function is called on the disk containing the operating system, it
will cause Windows 2000 to pop-up a message box telling that a new device has
been detected and that the computer needs to be restarted.
If the disk geometry has not changed and you have therefore not called this
function, but you are still getting the new device message on Windows 2000, it
might simply be that Windows detects the change of the hard disk serial number.
Use Win2KRegisterHDD to avoid this.

Example
NTCleanSignature(0);

361
Win2KRegisterHDD
Win2KRegisterHDD — Register a hard-drive into Win2k registry
Synopsis

Defined in
/plugins/ata.rbx

Function prototype

void Win2KRegisterHDD(bool verbose);

Description
This function scans the IDE controller for disk devices and register them into
Windows 2000 registry base to avoid a device redetection pop-up message box
during the first boot. If verbose is set to true, the operations done are logged to
the console window.
Note that in order to completely avoid the pop-up message, you should ensure that
your disks have the exact same geometry, that you are using the same partition
layout and that you did not only restore the partition content but also the master
boot record (MBR), which includes a Windows signature.

Example
Win2KRegisterHDD(true);

See also
See also NTCleanSignature, IDEDetect.

362
NTMapDrives
NTMapDrives — Retrieve Windows drive mappings
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var NTMapDrives(void);

Description
NTMapDrives scans the Windows registry in order to find the drive mapping
associated with each of the partitions located on the local hard drive. An array of
structures, with one structure per partition, is returned. The returned structure
contains information about the drive mapping and the physical location of the
partition on the hard drive (i.e. starting sector and total sector count).
A call to NTDetect() may be required if Windows is not installed in /windows on
the first partition of the hard drive.

Example
var map = NTMapDrives();
for (int i=0;i<sizeof(map);i++) {
Printf("Drive %s is rembo drive disk://%d:%d<br>",
map[i].drive,map[i].disk,map[i].partno);
}

See also
See also Win2KRegisterParts.

363
Win2KRegisterParts
Win2KRegisterParts — Update Windows partition layout
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void Win2KRegisterParts(void);

Description
Win2KRegisterParts updates partition information stored in the Windows registry
with actual partition information found on the local hard drive. This function is very
useful when an image is restored on a computer with a partition layout that is
different from the partition layout contained in the disk image: updating registry
with actual partition layout will avoid hardware redetection when Windows is
booting, thus avoiding an additional reboot.
A call to NTDetect() may be required if Windows is not installed in /windows on
the first partition of the hard drive.

Example
... restore image on hard disk ...
NTDetect();
Win2KRegisterParts();
HDBoot(0,1);

364
Win2KChangeIPInfo
Win2KChangeIPInfo — Set Windows networking settings manually
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void Win2KChangeIPInfo(bool verbose);

Description
Win2KChangeIPInfo updates the networking information for the primary network
card in the Windows registry to reflect current IP address and IP gateway. This
function is used to switch from a DHCP-based Windows configuration to a
statically configured IP address. The IP address used by REMBO to update the
registry is the one received from the PXE server during PXE boot.
If verbose is set to true, this function will print informative output in the console
window during execution.
A call to NTDetect() may be required if Windows is not installed in /windows on
the first partition of the hard drive.

Example
// display IP address
Printf("IP address is %s<br>",NetInfo.IPAddress);
NTDetect();
Win2KChangeIPInfo(true);

See also
See also Win2KChangeNameServers,

365
Win2KChangeNameServers
Win2KChangeNameServers — Set Windows DNS servers
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void Win2KChangeNameServers(str nameservers, bool verbose);

Description
Win2KChangeNameServers updates DNS name servers information in Windows
registry. The new DNS servers list is given as a space-separated list of IP addresses.
If verbose is set to true, this function will print informative output in the console
window during execution.
A call to NTDetect() may be required if Windows is not installed in /windows on
the first partition of the hard drive.

Example
str dnssrvs = "10.2.3.4 10.2.3.5";
NTDetect();
Win2KChangeNameServers(dnssrvs,true);

See also
See also Win2KChangeIPInfo,

366
NTSetBootTimeout
NTSetBootTimeout — Change Windows NT boot delay
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void NTSetBootTimeout(int timeout);

Description
This opens the boot.ini in the Windows NT partition and change the value of the
initial boot delay before the operating system starts. The timeout value is
measured in seconds.

Example
NTSetPartition(1);
NTSetBootTimeout(0);

367
NTSetNetbiosName
NTSetNetbiosName — Change the NETBIOS name of the local NT computer
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void NTSetNetbiosName(str name);

Description
This function opens the Windows NT registry and modifies the local computer
name stored in the SYSTEM key.
If the workstation is a member of a Windows NT domain, changing its name will
render the domain membership invalid, and you will be requested to rejoin the
domain either interactively (in NT) or automatically (with the NTJoinDomain
Rembo-C function).
The new computer name should be specified in uppercase characters, and should
not be longer than 15 characters.
By default, this function operates on registry files stored in the
winnt/system32/config directory of the first partition (disk://0:1). If Windows
NT is installed on a different partition, modify the value of the variable NTLocation.
The default value for NTLocation is disk://0:1.

Example
NTSetNetbiosName("REMBO");
NTLocation = "disk://0:2"; // NT on partition 2
NTSetNetbiosName("REMBO");

368
NTSetHostName
NTSetHostName — Change the TCP/IP name of the local NT computer
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void NTSetHostName(str name);

Description
This function opens the local SYSTEM registry file and modifies the hostname stored
in the TCP/IP settings (DNS hostname).
By default, this function operates on registry files stored in the
winnt/system32/config directory of the first partition (disk://0:1). If Windows
NT is installed on a different partition, modify the value of the variable NTLocation.
The default value for NTLocation is disk://0:1.

Example
NTSetHostName("rembo");

369
NTSetWinlogonDomain
NTSetWinlogonDomain — Change the logon name of the local NT computer
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void NTSetWinlogonDomain(str name);

Description
This function opens the local SOFTWARE registry file and modifies the domain name
used by WinLogon (NT login screen) when displaying the logon dialog box.
By default, this function operates on registry files stored in the
winnt/system32/config directory of the first partition (disk://0:1). If Windows
NT is installed on a different partition, modify the value of the variable NTLocation.
The default value for NTLocation is disk://0:1.

Example
NTSetWinlogonDomain("REMBO");

370
NTChangeName
NTChangeName — Changes the name of the local NT computer (shortcut)
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void NTChangeName(str name);

Description
This function is a shortcut to the three specific hostname modification functions
NTSetNetbiosName, NTSetHostName and NTSetWinlogonDomain. It is provided to
offer a convenient way to change all NT local names with one function call.
By default, this function operates on registry files stored in the
winnt/system32/config directory of the first partition (disk://0:1). If Windows
NT is installed on a different partition, modify the value of the variable NTLocation.
The default value for NTLocation is disk://0:1.

Example
NTChangeName("REMBO");
// is equivalent to
NTSetNetbiosName("REMBO");
NTSetHostName("REMBO");
NTSetWinlogonDomain("REMBO");

371
NTInstallService
NTInstallService — Install a service on the local NT computer
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void NTInstallService(str imagepath, str servicename, str


displayname);

Description
This function installs a new service in the system configuration of the local
Windows NT installation.
Parameter imagepath is the Windows NT path to the executable file for the
service. This path is used in Windows NT, and must be a valid NT path (e.g.
c:\temp\service.exe). The path should not contain spaces (use DOS short names
instead).
Parameter servicename is the internal name of the service in the service
database. This name is used to uniquely identify the service, but is not displayed in
any dialog box.
Parameter servicename is the visible name of the service. This is the string
displayed by the service manager in the control panel of Windows NT.
By default, this function operates on registry files stored in the
winnt/system32/config directory of the first partition (disk://0:1). If Windows
NT is installed on a different partition, modify the value of the variable NTLocation.
The default value for NTLocation is disk://0:1.

Example
NTInstallService("c:\temp\service.exe","myserv","My Service");

372
NTAutoLogon
NTAutoLogon — Change the auto logon information on the local NT computer
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void NTAutoLogon(str username, str password, str domain);

Description
This function modifies the autologon information for the local Windows NT
installation. The autologon information is a username and a password used to
automatically log into the computer instead of displaying the standard logon dialog.
The three parameters correspond to the three fields of the NT logon dialog box.
By default, this function operates on registry files stored in the
winnt/system32/config directory of the first partition (disk://0:1). If Windows
NT is installed on a different partition, modify the value of the variable NTLocation.
The default value for NTLocation is disk://0:1.

373
NTJoinDomain
NTJoinDomain — Join a NT domain
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void NTJoinDomain(void);
void NTADSJoinDomain(str OUPath);

Description
This function analyzes the local NT registry to determine for which domain this
workstation is configured, installs a new service in the NT service database, and
sends a joindomain request to the REMBO server.
Domain membership on Windows NT is handled by trust accounts. A trust account
is like a user account, but for computers. The password of the trust account is stored
on the server and on the computer, and this password is matched during the initial
packets sent by the domain member to the domain controller. If the password does
not match, the member cannot use domain resources.
If you clone NT workstations with REMBO, it is likely that you will have to modify
the hostname on clones, to avoid the situation where all computers have the same
name because this is not supported in Windows NT domains.
If you change the hostname with NTSetNetbiosName, a trust account with the same
name needs to be created on the server if you want to use domain resources (i.e. log
into the domain). REMBO can handle all this work automatically with a call to
NTJoinDomain. But the following conditions must be met:

• the master computer (the reference image for all clones) must have been
configured as a member of the domain you want to join (i.e. the clone is already
configured for the domain, except for the trust account);
• the REMBO server must run on a Windows NT computer and must have enough
privilege to modify computer accounts on the domain controller.

If conditions are met, NTJoinDomain will ask the REMBO server to create a new
trust account, and will then install a local service which will be run when Windows

374
NTJoinDomain
NT starts. This service will update the local information about the trust account
(trust account password) so that this information is synchronized with the server
information. This change might not be immediate if the service takes some time to
start (slow startup), or if the computer starts on a backup domain controlled not
synchronized with the primary domain controller.
The service removes itself from the service database once its task is completed.
By default, this function operates on registry files stored in the
winnt/system32/config directory of the first partition (disk://0:1). If Windows
NT is installed on a different partition, modify the value of the variable NTLocation.
The default value for NTLocation is disk://0:1.

If you are using Active Directory Services (ADS) in your company, it is


recommended to use NTADSJoinDomain instead of NTJoinDomain.
NTADSJoinDomain allows you to specify the Organizational Unit to use when
creating the computer account. The format of the OUPath is
"OU=factory1,DC=rembo,DC=com".

375
NTForcePwdChange
NTForcePwdChange — Force a user’s password to expire at next logon
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void NTForcePwdChange(str username);

Description
This function modifies the password information for a specific NT user so that the
user is asked to change its password at next logon. This is equivalent to the "User
must change password at next logon" checkbox in the user manager under
Windows NT/2000.
Note that the username must be a valid local NT user, and that the username is
case-sensitive.
By default, this function operates on registry files stored in the
winnt/system32/config directory of the first partition (disk://0:1). If Windows
NT is installed on a different partition, modify the value of the variable NTLocation.
The default value for NTLocation is disk://0:1.

376
GetSIDFromFile
GetSIDFromFile — Extract a SID from a file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var GetSIDFromFile(str filename);

Description
This function extracts a security identifier (SID) from the specified file. The file
must have the same format as the Domains/Account/V key in the SAM registry.
This function is used by GetSIDFromRegistry to extract the SID from a registry
file. You will probably never need to use GetSIDFromFile directly, but instead use
GetSIDFromRegistry.

See Section 3.3.7 in REMBO Client Administration Manual for a step-by-step guide
on how to modify the SID with REMBO

377
GetSIDFromRegistry
GetSIDFromRegistry — Extract a SID from a registry file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var GetSIDFromRegistry(str regfile);

Description
This function extracts the SID from the SAM/Domains/Account/V key of the
specified registry. The parameter regfile must refer to a SAM registry file, either
stored on disk, or in an archive.
If regfile is not specified, this function will try to extract the SID from the SAM
registry in winnt/system32/config on the NT partition (as defined by NTLocation.
by default, disk://0:1).
See Section 3.3.7 in REMBO Client Administration Manual for a step-by-step guide
on how to modify the SID with REMBO

Example
// get SID from the SAM on partition 1
var sid = GetSIDFromRegistry("");
// get SID from a NT image
OpenArchive("ntbase","cache://global/hdimages/winnt/base.img");
var sid =
GetSIDFromRegistry("arch://ntbase/winnt/system32/config/sam");
CloseArchive("ntbase");

378
ApplySID
ApplySID — Set SID information on an opened NTFS filesystem
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void ApplySID(str devpath, var oldsid, var newsid);

Description
This function sets parameters for NTFS on-the-fly SID replacement during image
restoration (using Synchronize). Parameter devpath must point to a NTFS
partition on which the hard disk image will be restored.
SID parameters are used by Synchronize to replace all occurences of oldsid by
newsid when copying files from the hard disk image to the target partition.
Parameter oldsid is the SID extracted from the hard disk image (using
GetSIDFromRegistry), while newsid is the SID to use for replacing occurences of
oldsid. newsid can have been generated with GenerateSID, or can be loaded
from a host specific file (in order to use the same SID for every restore).
Once SID parameters have been set on a partition with ApplySID, you cannot use
HDClean on that partition because it will clear the parameters. If you are performing
a full-restore, you should first execute HDClean, then ApplySID, and finally
Synchronize. You cannot use RestoreDiskImage as this function internally calls
HDClean.

See Section 3.3.7 in REMBO Client Administration Manual for a step-by-step guide
on how to modify the SID with REMBO

Example
// get source SID
OpenArchive("ntbase","cache://global/hdimages/winnt/base.img");
var oldsid =
GetSIDFromRegistry("arch://ntbase/winnt/system32/config/sam");
CloseArchive("ntbase");
// get destination SID from stored file or generate
var newsid;
if (FileExists("net://host/SID"))
newsid = LoadHexFile("net://host/SID");

379
ApplySID
else {
newsid = GenerateSID(oldsid);
// store generated SID
CreateHexFile("net://host/SID",newsid);
}
// Clean the target partition
HDClean(0,1);
// Apply SID
ApplySID("disk://0:1",oldsid,newsid);
// Restore image
Synchronize("cache://global/hdimages/winnt/base.img",
"disk://0:1","b");
// Patch registries
PatchSID(oldsid,newsid);

380
GenerateSID
GenerateSID — Generate a new random SID based on an existing SID
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var GenerateSID(var oldsid);

Description
This function generates a random SID based on an existing SID. Use this function
to generate a new unique host SID for use with ApplySID and PatchSID.
In many situations it is desirable to store this generated SID on a host specific file
and reload the SID from the file instead of generating a new SID on each
restoration. This will guarantee that a host always get the same SID, thus preventing
NT domain membership problems.
See Section 3.3.7 in REMBO Client Administration Manual for a step-by-step guide
on how to modify the SID with REMBO

Example
// get source SID
OpenArchive("ntbase","cache://global/hdimages/winnt/base.img");
var oldsid =
GetSIDFromRegistry("arch://ntbase/winnt/system32/config/sam");
CloseArchive("ntbase");
// get destination SID from stored file or generate
var newsid;
if (FileExists("net://host/SID"))
newsid = LoadHexFile("net://host/SID");
else {
newsid = GenerateSID(oldsid);
// store generated SID
CreateHexFile("net://host/SID",newsid);
}
// Clean the target partition
HDClean(0,1);
// Apply SID
ApplySID("disk://0:1",oldsid,newsid);
// Restore image

381
GenerateSID
Synchronize("cache://global/hdimages/winnt/base.img",
"disk://0:1","b");
// Patch registries
PatchSID(oldsid,newsid);

382
SIDToStr
SIDToStr — Get the textual representation of a binary SID
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str SIDToStr(var sid);

Description
This function returns the textual representation of a SID. This textual representation
is used by PatchSIDReg to replace textual SID occurences.
See Section 3.3.7 in REMBO Client Administration Manual for a step-by-step guide
on how to modify the SID with REMBO

Example
// get registry from partition 1
var sid = GetSIDFromRegistry("");
Log("My SID is "+SIDToStr(sid)+"<br>");

383
PatchSIDReg
PatchSIDReg — Replace all SID occurences in a registry file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

int PatchSIDReg(str regfile, var oldsid, var newsid);

Description
This function patches all the occurences (textual and binary) of oldsid with
newsid in the registry file specified by regfile.
In most cases you will call PatchSID instead of this function in order to patch the
SID in all registry files. This function is provided to allow you to patch registry files
not handled by PatchSID.
See Section 3.3.7 in REMBO Client Administration Manual for a step-by-step guide
on how to modify the SID with REMBO

Example
// get source SID from partition 1
var oldsid = GetSIDFromRegistry("");
// get destination SID from stored file or generate
var newsid;
if (FileExists("net://host/SID"))
newsid = LoadHexFile("net://host/SID");
else {
newsid = GenerateSID(oldsid);
// store generated SID
CreateHexFile("net://host/SID",newsid);
}
// Patch software registry
PatchSID("disk://0:1/winnt/system32/config/software",oldsid,newsid);

384
PatchSID
PatchSID — Replace all SID occurences in all registry files
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

int PatchSID(var oldsid, var newsid);

Description
This function replaces all the occurences (textual and binary) of oldsid with
newsid in Windows NT registry files. All five standard registry files are processed,
as well as user registries (NTUSER.DAT stored in local user profiles).
This function uses PatchSIDReg to patch individual registry files.
By default, this function operates on registry files stored in the
winnt/system32/config directory of the first partition (disk://0:1). If Windows
NT is installed on a different partition, modify the value of the variable NTLocation.
The default value for NTLocation is disk://0:1.
See Section 3.3.7 in REMBO Client Administration Manual for a step-by-step guide
on how to modify the SID with REMBO

Example
// get source SID
OpenArchive("ntbase","cache://global/hdimages/winnt/base.img");
var oldsid =
GetSIDFromRegistry("arch://ntbase/winnt/system32/config/sam");
CloseArchive("ntbase");
// get destination SID from stored file or generate
var newsid;
if (FileExists("net://host/SID"))
newsid = LoadHexFile("net://host/SID");
else {
newsid = GenerateSID(oldsid);
// store generated SID
CreateHexFile("net://host/SID",newsid);
}
// Clean the target partition
HDClean(0,1);
// Apply SID

385
PatchSID
ApplySID("disk://0:1",oldsid,newsid);
// Restore image
Synchronize("cache://global/hdimages/winnt/base.img",
"disk://0:1","b");
// Patch registries
PatchSID(oldsid,newsid);

386
5.6. INI file operations

NewIniFile
NewIniFile — Create an empty .ini file structure
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var NewIniFile(void);

Description
This function returns an empty .ini structure, that can later be modified by adding
sections and values, then saved in the traditionnal .ini file format.

Example
var myini = NewIniFile();
SetIniValue(myini, "Settings", "Mode", "recovery");
SetIniValue(myini, "Settings", "LastBoot", SystemInfo.Date);
CreateTextFile("disk://0:1/state.ini", BuildIniFile(myini));

387
ParseIniFile
ParseIniFile — Parse an existing .ini file into memory
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var ParseIniFile(str inifile);

Description
This function reads an .ini file in order to be able to change its content and then save
it back to an .ini file.

Example
var myini = ParseIniFile("disk://0:1/state.ini");
SetIniValue(myini, "Settings", "Mode", "recovery");
SetIniValue(myini, "Settings", "LastBoot", SystemInfo.Date);
CreateTextFile("disk://0:1/state.ini", BuildIniFile(myini));

See also
See also ParseIniFileDef, ParseIniString.

388
ParseIniFileDef
ParseIniFileDef — Parse an .ini file, or create a new structure
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var ParseIniFileDef(str inifile);

Description
This function reads an .ini file in order to be able to change its content and then save
it back to an .ini file. If the file does not exist, an empty .ini structure is returned.

Example
myini = ParseIniFileDef("disk://0:1/state.ini");
// is equivalent to
if(FileExists("disk://0:1/state.ini"))
myini = ParseIniFile("disk://0:1/state.ini");
else
myini = NewIniFile();

See also
See also ParseIniFile, ParseIniString.

389
ParseIniString
ParseIniString — Parse an .ini content stored in a string
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

var ParseIniString(str content);

Description
This function reads an .ini content (string made of several lines, following the .ini
format) in order to be able to change its content and then save it back to an .ini file.
This function performs the reverse of BuildIniFile.

Example
// read the ini file into a string
str content = LoadTextFile("disk://0:1/state.ini");
// parse the content
var myini = ParseIniString(content);
// change values
SetIniValue(myini, "Settings", "Mode", "recovery");
SetIniValue(myini, "Settings", "LastBoot", SystemInfo.Date);
// update the content string
content = BuildIniFile(myini);

See also
See also ParseIniFile, BuildIniFile.

390
BuildIniFile
BuildIniFile — Build an .ini content into a string for saving
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str BuildIniFile(var inistruct);

Description
This function creates the .ini string representation (several lines of text divided in
sections, etc.) of a structure describing settings as produced by ParseIniFile and
ParseIniString.

All values are quoted (bracketed by double-quotes). If you want a non-quoted


output, use BuildUnquotedIniFile. Note that the quotes are normally supported in
the .ini file format.
This function performs the reverse of ParseIniString.

Example
// read the ini file into a string
str content = LoadTextFile("disk://0:1/state.ini");
// parse the content
var myini = ParseIniString(content);
// change values
SetIniValue(myini, "Settings", "Mode", "recovery");
SetIniValue(myini, "Settings", "LastBoot", SystemInfo.Date);
// update the content string
content = BuildIniFile(myini);

See also
See also ParseIniFile, ParseIniString and BuildUnquotedIniFile.

391
BuildUnquotedIniFile
BuildUnquotedIniFile — Build an .ini content, without quoting values
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str BuildUnquotedIniFile(var inistruct);

Description
This function creates the .ini string representation (several lines of text divided in
sections, etc.) of a structure describing settings as produced by ParseIniFile and
ParseIniString.

This function does not quote any value. If you want a quoted output, use
BuildIniFile. Note that at least non-atomic values should be quoted in a normal
.ini file.
This function performs the reverse of ParseIniString.

Example
// read the ini file into a string
str content = LoadTextFile("disk://0:1/state.ini");
// parse the content
var myini = ParseIniString(content);
// change values
SetIniValue(myini, "Settings", "Mode", "recovery");
SetIniValue(myini, "Settings", "LastBoot", SystemInfo.Date);
// update the content string
content = BuildUnquotedIniFile(myini);

See also
See also ParseIniFile, ParseIniString and BuildUnquotedIniFile.

392
TestIniValue
TestIniValue — Check for the existence of a value in an .ini structure
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

bool TestIniValue(var inistruct, str section, str ident);

Description
This function checks for the presence of a specific identifier in a given section of an
.ini file loaded in memory.
To get the actual value associated to the identifier, use GetIniValue.

Example
var odbcini = ParseIniFile("disk://0:1/winnt/odbc.ini");
if(TestIniValue(odbcini,"MS Access Database","Driver32"))
Print("Access driver installed");

See also
See also ParseIniFile, GetIniValue and SetIniValue.

393
GetIniValue
GetIniValue — Retrieve a value from an .ini structure
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str GetIniValue(var inistruct, str section, str ident);

Description
This function returns the value associated with the given identifier in section of an
.ini file loaded in memory. If the section or the identifier is not found in the .ini file,
an empty string is returned.
To distinguish between no value and an empty value, use TestIniValue.

Example
var odbcini = ParseIniFile("disk://0:1/winnt/odbc.ini");
str xlsdriver = GetIniValue(odbcini,"Excel Files","Driver32");

See also
See also ParseIniFile, TestIniValue and SetIniValue.

394
GetIniStruct
GetIniStruct — Retrieve a section from an .ini structure
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

bool GetIniStruct(var inistruct, str section, var struc);

Description
This function updates the value of all fields defined in struc with values taken
from the specified section of an .ini file loaded in memory. The value for each
member of the structure is loaded from the corresponding identifier in the .ini file.
Members for which no value is specified in the .ini file are left unchanged, and
identifiers in the .ini file that are not part of the structure are not considered.
The function returns true if all assignments succeeded, and false otherwise. A
typical reason for failure is a non-numeric value in the .ini file for a numeric
member in the structure, or a non-boolean value in the .ini file for a numeric
member in the structure.
Arrays are acceptable as member of the structure. They are mapped to identifiers
with the array index as suffix, eg. item0, item1, etc.

Example
// instanciate a structure, with its default values
struct s_settings settings;
// read the values saved in an ini file
var config = ParseIniFile("net://global/config.ini");
if(!GetIniStruct(config, "Settings", settings))
Print("Error reading settings from ini file");

See also
See also ParseIniFile, GetIniValue and SetIniStruct.

395
SetIniValue
SetIniValue — Update a value in an .ini structure
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str SetIniValue(var inistruct, str section, str ident, str newvalue);

Description
This function change the value associated with the given identifier in a section of an
.ini file loaded in memory. If the section or the identifier is not found in the .ini file,
it is added to the file.
If you know in advance that the identifier does not yet exist in the .ini file (for
instance when you build a new .ini file from scratch), it is more efficient to use
AddIniValue.

Example
var myini = ParseIniFile("disk://0:1/state.ini");
SetIniValue(myini, "Settings", "Mode", "recovery");
SetIniValue(myini, "Settings", "LastBoot", SystemInfo.Date);
CreateTextFile("disk://0:1/state.ini", BuildIniFile(myini));

See also
See also ParseIniFile, GetIniValue and SetIniStruct.

396
SetIniStruct
SetIniStruct — Update a section in an .ini structure
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void SetIniStruct(var inistruct, str section, var struc);

Description
This function stores in an .ini file in memory the value of all members defined in
struc, under the specified section. The value for each member of the structure is
mapped to the corresponding identifier in the .ini file, whether it already exists or
not. Existing identifiers in the .ini file that have no counterparts in the structure are
left unchanged.
Arrays are acceptable as member of the structure. They are mapped to identifiers
with the array index as suffix, eg. item0, item1, etc.

Example
// instanciate a structure, with its default values
struct s_settings settings;
// ... do some work, determine settings
// save the configuration ini file
var config = ParseIniFile("net://global/config.ini");
SetIniStruct(config, "Settings", settings);
CreateTextFile("net://global/config.ini", BuildIniFile(config));

See also
See also ParseIniFile, SetIniValue and GetIniStruct.

397
AddIniValue
AddIniValue — Add a new value in an .ini structure
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str AddIniValue(var inistruct, str section, str newident, str


newvalue);

Description
This function adds a new identifier/value pair in a section of an .ini file loaded in
memory. If the section is not found in the .ini file, it is added to the file.
Note that this function does not perform any check to verify that the identifier does
not already exists in the section. If you are not positively sure that the identifier is
new, use SetIniValue instead.

Example
var myini = NewIniFile();
AddIniValue(myini, "Settings", "Mode", "recovery");
AddIniValue(myini, "Settings", "LastBoot", SystemInfo.Date);
CreateTextFile("disk://0:1/state.ini", BuildIniFile(myini));

See also
See also NewIniFile, SetIniValue and AddIniSection.

398
AddIniSection
AddIniSection — Add a new section in an .ini structure
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str AddIniSection(var inistruct, str section);

Description
This function adds a new empty section in an .ini file loaded in memory. If the
section already exists, the function has no effect.

Example
var myini = NewIniFile();
AddIniSection(myini, "Settings");
CreateTextFile("disk://0:1/state.ini", BuildIniFile(myini));

See also
See also NewIniFile, SetIniValue.

399
DiffIniFile
DiffIniFile — Compare two .ini files and extract differences
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str DiffIniFile(str file1, str file2);

Description
This function reads the two specified .ini files and compare their logical content to
detect any added, removed or changed value. The order of sections and identifiers in
the sections is not taken into account. A non-existing file is considered as an empty
file.
The result of the comparison is returned in a proprietary but intuitive text format,
understood by PatchIniFile.

Example
str modif = DiffIniFile("cache://global/ref.ini", "disk://0:1/data.ini");
PatchIniFile("cache://global/ref.ini", modif, "disk://0:1/data2.ini");

See also
See also PatchIniFile.

400
PatchIniFile
PatchIniFile — Apply a set of modifications to an .ini file
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void PatchIniFile(str file1, str patchstr, str file2);

Description
This function reads the .ini file pointed by file1, apply all changes specified in
patchstr and saves the result in file2.
The format of the patch string is as returned by DiffIniFile.

Example
str modif = DiffIniFile("cache://global/ref.ini", "disk://0:1/data.ini");
PatchIniFile("cache://global/ref.ini", modif, "disk://0:1/data2.ini");

See also
See also DiffIniFile.

401
5.7. Hardware and network detection

GetPnPCards
GetPnPCards — Retrieve the array of PnP cards
Synopsis

Defined in
Built-in function.

Function prototype

var GetPnPCards(void);

Description
This function performs a Plug&Play hardware detection and returns an array
describing all PnP devices detected in the computer.
The returned array is an array of strings, each string describing a separate PnP
device. The format of these strings is XXXX:zzz, where XXXX is the EISA code for
the PnP device, and zzz a device description string.

Example
var pnp = GetPnPCards();
for (int i=0;i<sizeof(pnp);i++)
Log("Card "+(str)i+" is "+pnp[i]+"<br>");

402
GetSystemDevices
GetSystemDevices — Retrieve the array of system devices
Synopsis

Defined in
Built-in function.

Function prototype

var GetSystemDevices(void);

Description
This function perform a hardware detection of system devices (devices attached to
the motherboard) and returns an array describing detected devices.
The returned array is an array of strings, each string describing a separate system
device. The format of these strings is EEEE:DDDD, where EEEE is the EISA code of
the system device, and DDDD is the device ID for the system device.

403
GetPCICards
GetPCICards — Retrieve the array of PCI cards
Synopsis

Defined in
Built-in function.

Function prototype

var GetPCICards(void);

Description
This function performs a PCI hardware detection and returns a string describing all
PCI devices detected in the computer.
The returned array is an array of strings, each string describing a separate PnP
device. The format of these strings is VVVV:DDDD:bb:dd:class, where

• VVVV is the vendor ID of the PCI device;


• DDDD is the device ID of the PCI device;
• bb is the bus number which the device is attached to;
• dd is the device number on the bus for the PCI device;
• class is one of RES (reserved), DISK (disk controller), NET (network device),
DISP (display), MEDIA (multimedia), MEM (memory device), BRIDGE (internal PCI
bridge), COMM (communication device), SYS (system device), INPUT (input
device), DOCK, CPU, SER (serial device).

Example
var pci = GetPCICards();
for (int i=0;i<sizeof(pci);i++)
Log("Card "+(str)i+" is "+pci[i]+"<br>");

404
PCIFindDevice
PCIFindDevice — Find a PCI device given its vendor/device ID
Synopsis

Defined in
Built-in function.

Function prototype

var PCIFindDevice(int vendor, int device, int devidx);

Description
This function returns a structure containing information about the devidx-th PCI
device with the specified vendor ID / device ID pair. An exception is raised if the
device cannot be found.
The returned structure contains the following fields:

• int bus: bus index of device found


• int device: device index of device found
• int function: function number of device found

PCIFindDevice is provided for low-level access to PCI devices. It is directly


mapped to INT 1A, fn B102.

Example
// Display info about an EEPRO100
LogVar(PCIFindDevice(0x8086,0x1229,0));

405
PCIGetBusCount
PCIGetBusCount — Get the total number of PCI buses
Synopsis

Defined in
Built-in function.

Function prototype

int PCIGetBusCount(void);

Description
This function returns the index of the last PCI bus found. This is the same
information as returned by INT 1A, fn B101.
The information returned by this function can be used when enumerating PCI
devices. It should only be used to gain low-level access to PCI devices.

406
PCIGetSlot
PCIGetSlot — Get the PCI slot number for a given device
Synopsis

Defined in
Built-in function.

Function prototype

int PCIGetSlot(int bus, int dev);

Description
This function returns the slot number for a PCI device, given by its bus and device
number. The information is taken from the computer interrupt routing table.
On-board devices return the value zero.

407
PCIReadByte
PCIReadByte — Read a byte in PCI registers
Synopsis

Defined in
Built-in function.

Function prototype

int PCIReadByte(int bus, int dev, int fun, int reg);

Description
This function returns the value of the PCI byte (8-bits) register reg for device
specified by bus, dev,fun. This function is directly mapped to INT 1A, fn B108.
This function is provided for low-level access to PCI devices. Do not use this
function if you do not have sufficient knowledge of PCI architecture.

408
PCIReadWord
PCIReadWord — Read a word in PCI registers
Synopsis

Defined in
Built-in function.

Function prototype

int PCIReadWord(int bus, int dev, int fun, int reg);

Description
This function returns the value of the PCI word (16-bits) register reg for device
specified by bus, dev,fun. This function is directly mapped to INT 1A, fn B109.
This function is provided for low-level access to PCI devices. Do not use this
function if you do not have sufficient knowledge of PCI architecture.

409
PCIReadDWord
PCIReadDWord — Read a double-word in PCI registers
Synopsis

Defined in
Built-in function.

Function prototype

int PCIReadDWord(int bus, int dev, int fun, int reg);

Description
This function returns the value of the PCI double-word (32-bits) register reg for
device specified by bus, dev,fun. This function is directly mapped to INT 1A, fn
B10A.
This function is provided for low-level access to PCI devices. Do not use this
function if you do not have sufficient knowledge of PCI architecture.

410
PCIWriteByte
PCIWriteByte — Write a byte in PCI registers
Synopsis

Defined in
Built-in function.

Function prototype

void PCIWriteByte(int bus, int dev, int fun, int reg, int val);

Description
This function writes val int the PCI byte (8-bits) register reg for device specified
by bus, dev,fun. This function is directly mapped to INT 1A, fn B10B.
This function is provided for low-level access to PCI devices. Do not use this
function if you do not have sufficient knowledge of PCI architecture.

411
PCIWriteWord
PCIWriteWord — Write a word in PCI registers
Synopsis

Defined in
Built-in function.

Function prototype

void PCIWriteWord(int bus, int dev, int fun, int reg, int val);

Description
This function writes val int the PCI word (16-bits) register reg for device
specified by bus, dev,fun. This function is directly mapped to INT 1A, fn B10C.
This function is provided for low-level access to PCI devices. Do not use this
function if you do not have sufficient knowledge of PCI architecture.

412
PCIWriteDWord
PCIWriteDWord — Write a double-word in PCI registers
Synopsis

Defined in
Built-in function.

Function prototype

void PCIWriteWord(int bus, int dev, int fun, int reg, int val);

Description
This function writes val int the PCI double-word (32-bits) register reg for device
specified by bus, dev,fun. This function is directly mapped to INT 1A, fn B10D.
This function is provided for low-level access to PCI devices. Do not use this
function if you do not have sufficient knowledge of PCI architecture.

413
PortOutByte
PortOutByte — Output a byte in a I/O port
Synopsis

Defined in
Built-in function.

Function prototype

void PortOutByte(int port, int val);

Description
This function writes the byte val in the I/O port port. Use this function with
caution since it provides a low-level access to peripherals and system devices.
This function is functionally equivalent to:
mov al, val
mov dx, port
out dx, al

414
PortOutWord
PortOutWord — Output a word in a I/O port
Synopsis

Defined in
Built-in function.

Function prototype

void PortOutWord(int port, int val);

Description
This function writes the word (16-bits) val in the I/O port port. Use this function
with caution since it provides a low-level access to peripherals and system devices.
This function is functionally equivalent to:
mov ax, val
mov dx, port
out dx, ax

415
PortInByte
PortInByte — Input a byte in a I/O port
Synopsis

Defined in
Built-in function.

Function prototype

int PortInByte(int port);

Description
This function reads a byte from the I/O port port. Use this function with caution
since it provides a low-level access to peripherals and system devices.
This function is functionally equivalent to:
mov dx, port
in al, dx
mov val, al

416
PortInWord
PortInWord — Input a word in a I/O port
Synopsis

Defined in
Built-in function.

Function prototype

int PortInWord(int port);

Description
This function reads a word from the I/O port port. Use this function with caution
since it provides a low-level access to peripherals and system devices.
This function is functionally equivalent to:
mov dx, port
in ax, dx
mov val, ax

417
HWSignature
HWSignature — Get the hardware signature
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

str HWSignature(void);

Description
You can use this function to retrieve a unique identifier for the hardware installed in
the computer. This signature is created from the list of installed Plug-and-Play, PCI
and system devices. A hash function is used to create a signature from the list of
devices.
HWSignature can be used to uniquely identify a hardware configuration, and
provide OS installation or OS configuration based on this hardware signature.

418
GetDMITables
GetDMITables — Retrieve a SMBIOS DMI table
Synopsis

Defined in
Built-in function.

Function prototype

var GetDMITables(int table);

Description
This function retrieves all the DMI tables corresponding to a specific DMI table
index. If the computer does not support DMI (SMBIOS), an exception is raised.
GetDMITable returns a binary object containing an exact copy of the table. You can
then use binary manipulation functions to extract values from the table. If you need
to extract a string given a string index, use GetDMIStrings.
DMIProcessorInfo, DMISystemInfo, DMIMemoryInfo, DMIBIOSInfo,
DMIOnBoardDev are high-level functions using GetDMITables to extract valuable
information about the local computer.

419
GetDMIStrings
GetDMIStrings — Retrieve strings associated with a DMI table
Synopsis

Defined in
Built-in function.

Function prototype

var GetDMIStrings(var table);

Description
This function extracts the DMI strings stored in the DMI table stored in the given
binary object. The DMI table should have been retrieved using GetDMITables.
GetDMIStrings returns an array of strings which can then be used retrieve the string
corresponding to a string index in a DMI table.
See the implementation of one of the high-level DMI functions for more details.

420
DMIProcessorInfo
DMIProcessorInfo — Retrieve DMI information about the processor
Synopsis

Defined in
/plugins/dmi.rbx

Function prototype

var DMIProcessorInfo(void);

Description
This function retrieves information about the installed processor(s) using DMI.
DMIProcessorInfo returns a structure with the following members:

• int count: the number of processors;


• str manufacturer: processor manufacturer string;
• str vers: processor version string;
• str socket: type of processor socket (SLOT1, ...);
• int speed: processor’s current speed (in Mhz);
• int l1cache: size of L1 cache in kilobytes;
• int l2cache: size of L2 cache in kilobytes.

Example
LogVar(DMIProcessorInfo());

421
DMISystemInfo
DMISystemInfo — Retrieve DMI information about the processor
Synopsis

Defined in
/plugins/dmi.rbx

Function prototype

var DMISystemInfo(void);

Description
This function retrieves information about the system using DMI.
DMISystemInfo returns a structure with the following members:

• str manufacturer: system manufacturer string;


• str product: product description string;
• str version: product version string;
• str serial: product serial number;
• str uuid: system unique identifier (UUID);
• str wakeup: source of last power on event (can be "PowerSwitch",
"LANRemote", ...).

Example
LogVar(DMISystemInfo());

422
DMIMemoryInfo
DMIMemoryInfo — Retrieve DMI information about the memory
Synopsis

Defined in
/plugins/dmi.rbx

Function prototype

var DMIMemoryInfo(void);

Description
This function retrieves information about the memory using DMI.
DMIMemoryInfo returns a structure with the following members:

• int count: the number of memory sockets;


• var modules: an array of moduleinfo structures, with one structure per memory
socket.

The moduleinfo structure is made of the following fields:

• int size: the size of installed module in kilobytes;


• str type: the type of installed module;
• int speed: the speed of installed module in nanoseconds;
• bool dblbank: true if the module has a double-bank connection.

Example
LogVar(DMIMemoryInfo());

423
DMIBIOSInfo
DMIBIOSInfo — Retrieve DMI information about the BIOS
Synopsis

Defined in
/plugins/dmi.rbx

Function prototype

var DMIBIOSInfo(void);

Description
This function retrieves information about the BIOS using DMI.
DMIBIOSInfo returns a structure with the following members:

• str vendor: BIOS vendor string;


• str version: BIOS version string;
• str release: BIOS release string;
• bool flashable: true if BIOS is flashable.

Example
LogVar(DMIBIOSInfo());

424
DMIOnBoardDev
DMIOnBoardDev — Retrieve the list of on board devices (DMI)
Synopsis

Defined in
/plugins/dmi.rbx

Function prototype

var DMIOnBoardDev(void);

Description
This function retrieves information about the motherboard devices using DMI.
DMIOnBoardDev returns a structure with the following members:

• int count: the number of memory sockets;


• var devices: an array of deviceinfo structures, with one structure per onboard
device.

The deviceinfo structure is made of the following fields:

• bool enabled: true if the onboard device is enabled;


• str type: onboard device type string;
• str description: onboard device description string;

Example
LogVar(DMIOnBoardDev());

425
GetExtDiskInfo
GetExtDiskInfo — Get extended information about a BIOS disk
Synopsis

Defined in
Built-in function.

Function prototype

var GetExtDiskInfo(int disknum);

Description
This function retrieves extended information about a specified disk detected by the
BIOS, as returned by the BIOS extended int 13h function.
GetExtDiskInfo returns a structure with the following members:

• InterfaceType: the type of interface on which the disk is connected (IDE,


SCSI), if the BIOS reports it.
• InterfaceNumber: the interface number, within its type (for instance 0 for the
primary IDE controller and 1 for the secondary IDE controller).
• DiskNumber: the disk number within its controller, for instance 0 for a master
IDE drive and 1 for a slave IDE drive, or the LUN id for SCSI drives.

Example
LogVar(GetExtDiskInfo(0));

See also
See also IDEDetect.

426
IDEDetect
IDEDetect — Get information for all ATA (IDE) disks
Synopsis

Defined in
/plugins/ata.rbx

Function prototype

var IDEDetect(void);

Description
This function issue to the ATA controller a command to retrieve the information
block for all IDE devices connected to the computer. This information includes the
disk vendor name, serial number, etc. if provided on the device. The function will
list all IDE devices, included ATAPI CD-Rom and removable hard-drives (ZIP
drive).
IDEDetect returns an array of structures with the following members:

• controller: the controller number to which the device is connected (0 for the
primary controller, 1 for the secondary controller).
• DiskNumber: the disk number within its controller (0 for the master IDE drive
and 1 for the slave IDE drive).
• type: the type of interface used by the device (ATA/ATAPI).
• media: the media type (Disk, CD-ROM, Tape).
• removable: a boolean telling if the device supports removable media or not.
• capacity: the hardware capacity of the media, or zero if unknown. Note that the
hardware capacity may not always match the logical capacity, due to formatting
constraints.
• model: the device model ID, if provided by the vendor.
• firmware: the device firmware verson, if provided by the vendor.
• serial: the device serial number, if provided by the vendor.
• winname: the model/firmware version, in the same format as used by Windows
2000 to identify hard-disks in the registry.

427
IDEDetect
• winserial: the serial number, in the same format as used by Windows 2000 to
identify hard-disks in the registry.

Example
LogVar(IDEDetect(0));

See also
See also Win2KRegisterHDD and GetExtDiskInfo.

428
Win2KRegisterBootDevice
Win2KRegisterBootDevice — adds the PCI IDE controller to device list
Synopsis

Defined in
/plugins/utils.rbx

Function prototype

void Win2KRegisterBootDevice(void);

Description
This function adds the PCI IDE controller to the list of devices needed to boot
Windows. This function is to be used to fix the
’INACCESSIBLE_BOOT_DEVICE’ error when an image is used on a disk
controller that is not compatible with the disk controller on the reference computer.
However this function will not load the IDE controller driver, the suitable driver
must therefore be contained in your image.

429
GetNICType
GetNICType — Retrieve PCI information about the PXE adapter
Synopsis

Defined in
Built-in function.

Function prototype

var GetNICType(void);

Description
This function retrieves information about the currently active PXE network adapter
(the one on which the computer has been started).
GetNICType returns a structure with the following members:

• vendorid: the PCI vendor identifier of the network adapter.


• deviceid: the PCI device identifier of the network adapter.
• bus: the PCI bus on which the device has been found (zero if it is a built-in
network card).
• device: the PCI device address of the network adapter on its bus.
• function: the PCI function address of the network adapter on its device.

Example
LogVar(GetNICType());

430
GetNICs
GetNICs — Retrieve information about all network adapters
Synopsis

Defined in
/plugins/getnics.rbx

Function prototype

var GetNICs(void);

Description
This function scans PCI devices and locate all network adapters. If the function
recognize a know type of adapter, it will then attempt to read the NIC serial
EEPROM to get the MAC address. Current version works on Intel EEPro, 3com
3c90x and RealTek cards (although it may not necessarily work on all future
models).
GetNICsreturns an array, each member of which is a structure with the following
members:

• vendid: the PCI vendor identifier of the network adapter.


• devid: the PCI device identifier of the network adapter.
• bus: the PCI bus on which the device has been found (zero if it is a built-in
network card).
• dev: the PCI device address of the network adapter on its bus. * This function
adds the PCI IDE controller to the list of devices needed to boot Windows. * This
function is to be used to fix the ’INACCESSIBLE_BOOT_DEVICE’ error when
an image is * used on a disk controller that is not compatible with the disk
controller on the reference computer
• fun: the PCI function address of the network adapter on its device.
• macaddr: a string encoding the MAC address, as hexadecimal bytes separated by
columns, or the string "(unknown NIC)" if the type of adapter is unknown.

Example
LogVar(GetNICs());

431
GetNICs

432
ProbeServer
ProbeServer — Check if a Rembo server is online
Synopsis

Defined in
built-in function.

Function prototype

bool ProbeServer(str ipaddr, int port, int secs, bool encrypted);

Description
ProbeServer sends a packet to ipaddr to discover if there is a running REMBO
server on that machine.
If the encrypted parameter is set to false, the primitive simply checks if there is
a REMBO server at the given IP address. Otherwise, if the parameter is set to true,
the primitive will check that a REMBO server is running and that the ’netpassword’
is correct (encrypted packets work).

• str ipaddr: the IP address of the server to probe


• int port: the ’NBP port’ for this server, or 0 to use default port
• int secs: the number of seconds to wait before timing out
• bool encrypted: whether to probe with an encrypted packet or not

Example
if (ProbeServer("192.168.1.4",0,5,true)) {
// server is alive
LogDir("net://192.168.1.4");
} else
Printf("Server 1.4 is down<br>");

See also
See also GetNetPass, GetServerInfo

433
RequestDHCPInfo
RequestDHCPInfo — Trigger a DHCP negotiation and create DHCP variables
Synopsis

Defined in
/plugins/dmi.rbx

Function prototype

void RequestDHCPInfo(void);

Description
RequestDHCPInfo sends a secondary DHCP request, asking the server for all known
configuration options. When the DHCP reply is received, global variables are
created for all options returned by the server. These variables can be used later on
by your scripts to customize configuration files using PatchFile for instance.
It is necessary to explicitely make a secondary DHCP request because the first
DHCP request automatically made by the bootrom at boot time only ask for the
minimum of information required to start the network boot program. Therefore, the
primary reply only contains a limited subset of the information available in the
DHCP server, and misses essential configuration options.
RequestDHCPInfo fills the global structure variable DHCPInfo with information
collected via DHCP. You can display all the members of the DHCPInfo structure
with LogVar(DHCPInfo);. You can then access a specific member with
DHCPInfo.xxx where xxx is the name of the member you want to access.

If you only need the client’s own network informations, you can use the following
variables directly, without having to invoke RequestDHCPInfo:

• NetInfo.MACAddress

• NetInfo.IPAddress

• NetInfo.SubnetMask

• NetInfo.DefaultGateway

See also
See also PatchFile, ReleaseDHCP.

434
ReleaseDHCP
ReleaseDHCP — Tell DHCP server that the address can be reused
Synopsis

Defined in
built-in function.

Function prototype

void ReleaseDHCP(void);

Description
ReleaseDHCP sends a request to the DHCP server, telling that the client’s IP address
can be reused immediately.
This can be useful if you need to reuse the IP address before the lease expiration
mechanism operates. For instance if your REMBO clients must share a small range
of IP addresses.

Make sure that the client will not access the network using the IP address
after releasing it. The network may be severly disturbed if the DHCP server
immediately gives the same address to another host.
It’s safe to use the function just before Reboot, PowerOff, or starting an OS that
uses a fixed IP address.

See also
See also RequestDHCPInfo: Trigger a DHCP negotiation and create DHCP
variables.

435
LoadUNDI
LoadUNDI — Load the PXE UNDI layer into the memory
Synopsis

Defined in
Built-in function.

Function prototype

void LoadUNDI(void);

Description
LoadUNDI scans the computer high-memory area to locate a PXE ROM header. If
one is found, it is loaded in low memory as the BIOS would have done at the
beginning of a network boot.
This function is useful to activate network connectivity within Rembo when the
computer has started on the hard-disk insted of PXE.
Note that this function does not yet initializes the network adapter and connect to
the server. Use the function SetIPInfo to do so.

See also
See also SetIPInfo and GetNetPass

436
SetIPInfo
SetIPInfo — Activate an IP stack over PXE UNDI layer
Synopsis

Defined in
Built-in function.

Function prototype

void SetIPInfo(str ipaddr, str netmask, str gateway, str nbpserver,


str password);

Description
SetIPInfo initialize a PXE adapter previously activated using LoadUNDI, according
to specified parameters. This function is useful to activate network connectivity
within Rembo when the computer has started on the hard-disk insted of PXE.
The ipaddr is the desired IP address for the client, in the usual decimal dotted
form. If left empty, the function will issue a DHCP request to receive a dynamic IP
address from a DHCP server. Otherwise, the parameters netmask and gateway
should specify the corresponding network mask and default gateway.
The nbpserver is the IP address of the default Rembo server to contact as
primary server. In order to access it, the NetFS password must also be provided.
Note that password is either a plain-text NetFS password or a MD5 representation
of the NetFS password, as returned by GetNetPass (in this case, the MD5 password
must given in parenthesis).

Example
// Activate PXE if needed, using DHCP
if((int)NetInfo.IPAddress == 0) {
LoadUNDI()
SetIPInfo("","","","192.168.1.9","password");
}

See also
See also LoadUNDI and GetNetPass.

437
GetNetPass
GetNetPass — Retrieve NETFs password
Synopsis

Defined in
built-in function.

Function prototype

var GetNetPass(void);

Description
GetNetPass returns a 16-bytes binary object containing an MD5 representation of
the NetFS password. The NetFS password is the password used by REMBO clients
and netclnt to access the REMBO server.
This function is primarily used to store a copy of the NetFS password locally in
order to use this value as the last parameter to the offline function SetIPInfo.

Example
if ((int)NetInfo.IPAddress==0) {
// connected to the server. store password
str pwd = Strf("(%s)",BinToHex(GetNetPass()));
Export(pwd,"ServerPwd","local");
Export(HostInfo.RemboServer,"ServerIP","local");
} else {
// offline, start networking
LoadUNDI();
SetIPInfo("","","",ServerIP,ServerPwd);
}

See also
See also SetIPInfo and LoadUNDI

438
GetServerInfo
GetServerInfo — Retrieve server information
Synopsis

Defined in
built-in function.

Function prototype

var GetServerInfo(void);

Description
GetServerInfo returns a structured variable with informations about the REMBO
server. The main structure members are:

• str Product: the major version number and product name, e.g. "2.0 Toolkit";

• str Build: the minor version number, e.g. "034.1";


• str OS: the type of Operating System on which the server is running, either
"Windows" or "Unix";

• int DebugLevel: the debug level currently used for server logs;
• str Config: where the server reads its configuration from, either "Registry" or
"File";

• int TimeZone: current difference between UTC and local time on the server in
seconds. Add this value to CMOS time on the client (SystemInfo.Date) if you
need UTC. This value also takes into account Daylight Saving information. For
instance in Switzerland (1 hour east of Greenwich) the value is -3600 in winter
and -7200 in summer.
• str LicensedTo: information found in the server’s activation key;
• str Reseller: information found in the server’s activation key;
• int MaxSeats: information found in the server’s activation key;
• int UsedSeats: number of different IP addresses served so far

439
5.8. Crypto and authentication functions

MD5Create
MD5Create — Initialize a MD5 computation
Synopsis

Defined in
Built-in function.

Function prototype

var MD5Create(void);

Description
This function creates a new MD5 object which can then be used with MD5Update
and MD5Finish to create a MD5 digest of a binary object.

Example
var m = MD5Create();
var b = LoadFile("net://global/testfile");
MD5Update(m,b,0,sizeof(b));
var md5 = MD5Finish(m);
Log("MD5 = "+BinToHex(md5)+"<br>");

440
MD5Update
MD5Update — Update a MD5 computation
Synopsis

Defined in
Built-in function.

Function prototype

void MD5Update(var md5state, var bin, int pos, int len);

Description
This function adds the binary data specified by bin (from pos for len bytes) to
the MD5 object specified by md5state.
The MD5 object md5state can then be transformed in a digest with MD5Finish.

Example
var m = MD5Create();
var b = LoadFile("net://global/testfile");
MD5Update(m,b,0,sizeof(b));
var md5 = MD5Finish(m);
Log("MD5 = "+BinToHex(md5)+"<br>");

441
MD5Finish
MD5Finish — Terminate a MD5 computation
Synopsis

Defined in
Built-in function.

Function prototype

var MD5Finish(var md5state);

Description
This function transforms a MD5 object in a digest. The digest is returned as a
binary variable containing 16 bytes.

Example
var m = MD5Create();
var b = LoadFile("net://global/testfile");
MD5Update(m,b,0,sizeof(b));
var md5 = MD5Finish(m);
Log("MD5 = "+BinToHex(md5)+"<br>");

442
BlowFishEncrypt
BlowFishEncrypt — Crypt a binary block using Blowfish
Synopsis

Defined in
Built-in function.

Function prototype

var BlowFishEncrypt(str key, var binarydata);

Description
This function encrypts a binary block using the blowfish algorithm, for the key
given as first argument. The result can be decoded back to the original data using
the BlowFishDecrypt function.
Crypting information will hide its content, but the decryption function will return
whatever key is given to decrypt the data (even if the original data will only be
recovered if the proper key is used). To ensure that the valid key is used and that the
original message is effectively decoded, you should combine the encryption with a
MD5-based message signature.

Example
var secretdata = BinFromStr("Hello world");
var crypted = BlowFishEncrypt("password", secretdata);
var decrypted = BlowFishDecrypt("password", crypted);
Print("Decrypted message is: ", BinToStr(decrypted));

443
BlowFishDecrypt
BlowFishDecrypt — Decrypt a binary block using Blowfish
Synopsis

Defined in
Built-in function.

Function prototype

var BlowFishDecrypt(str key, var crypteddata);

Description
This function decrypts a binary block using the blowfish algorithm, for the key
given as first argument. The crypted binary block given as argument should be the
result of a previous call to the BlowFishEncrypt function.
Crypting information will hide its content, but the decryption function will return
whatever key is given to decrypt the data (even if the original data will only be
recovered if the proper key is used). To ensure that the valid key is used and that the
original message is effectively decoded, you should combine the encryption with a
MD5-based message signature.

Example
var secretdata = BinFromStr("Hello world");
var crypted = BlowFishEncrypt("password", secretdata);
var decrypted = BlowFishDecrypt("password", crypted);
Print("Decrypted message is: ", BinToStr(decrypted));

444
AuthUser
AuthUser — Authenticate a user against a preset domain
Synopsis

Defined in
AuthUser: Built-in function.
LogonUser: /plugins/utils.rbx

Function prototype

bool AuthUser(str username, str password);


void LogonUser(str username, str password);

Description
AuthUser will try to authenticate a given user on the REMBO server, using a given
password. The implementation of the authentication depends on the
authentication domain setting of the server. If there is no authentication domain
set, the user will be granted access. See Section 2.3 in REMBO Server
Administration Manual for more information on server authentication settings.
The result of the authentication is stored in the global variable AuthInfo. AuthInfo
is a structure containing the following members:

• bool Success: is true if the authentication was successful;


• str UserName: the username of the logged in user (valid only if Success is
true);

• str Password: the password of the logged in user (valid only if Success is
true);

• str FullName: the full name of the logged in user (valid only if Success is
true). The full name might be empty if the authentication server has no full name
information for the logged in user;

If the authentication is sucessful, AuthUser executes the file net://user/autoload


which contains the persistent variables for the logged on user.
AuthUser is the low-level primitive used by LogonUser to perform authentication.
The difference between AuthUser and LogonUser is that AuthUser does not restore
the persistent variables of the user (stored in net://user/autoload).

445
AuthUser
If you want to perform authentication with a dialog box asking for the username
and password, consider using the high-level Logon function.

Example
AuthUser("john","johnpass");
if (AuthInfo.Success)
Log("You were successfully authenticated<br>");
else
Log("You are not welcome on this computer<br>");

See also
See also AuthUserEx.

446
AuthUserEx
AuthUserEx — Authenticate a user against an arbitrary domain
Synopsis

Defined in
AuthUserEx: Built-in function.

Function prototype

bool AuthUserEx(str username, str password, str authinfo);

Description
AuthUserEx behaves exactly like AuthUser. The difference is that AuthUserEx
authenticates a user against an arbitrary domain while AuthUser authenticates a user
against a preset domain. It has therefore one more parameter: authinfo defining an
authentication domain. The format of the string authinfo is of type:
type:info1:info2.

Here is a quick reference for possible authentication domains:

• Local domains local:group: use the local user database to authentify a user.
The optional group parameter can be used to restrict the verification to a specific
group of users.This type of domain is supported by both NT and Unix versions of
the REMBO server.
• Remote NT domains nt:server:group: forward authentication requests to the
NT server specified by the mandatory parameter server. The optional user can
be used to restrict the verification to a specific group of users. This type of
domain is supported by the NT implementation of the REMBO server only.
• Radius domains radius:ipaddr:secret: forward authentication requests to the
Radius-compliant device specified by the parameter ipaddr. The value of the
parameter secret is used as the secret for the Radius communication, and must
match the secret stored in the configuration of the Radius device for the protocol
to work.

The authenticated domain will however only be valid for the current request.

447
AuthUserEx
See also
See also AuthUser and Section 2.3 in REMBO Server Administration Manual for
more information on server authentication settings.

448
5.9. TCP connectivity functions

TCPConnect
TCPConnect — Initiate a TCP connection
Synopsis

Defined in
Built-in function.

Function prototype

int TCPConnect(str tunnelname);

Description
This function opens a connection through a TCP tunnel setup on the REMBO
server. The final destination of this TCP connection is determined by the parameters
of the corresponding TCP tunnel as setup on the server.
Parameter tunnelname is the identifier of the TCP tunnel to use. It must match an
existing TCP tunnel in the server configuration. A connection number is returned by
TCPConnect to identify this connection in calls to other TCP functions (TCPRead,
TCPWrite and TCPClose).

A connection open with TCPConnect must be closed by a call to TCPClose. If a


connection is kept open without any activity during more than 60 seconds, it is
automatically closed by the REMBO server.
If the connection request fails on the server side (connection refused, invalid TCP
hostname, connection timed out), an exception is raised by TCPConnect.

Example
On the server, create a TCP tunnel named finger pointing to a Unix or NT server
setup to answer finger requests:
TCPTunnel finger {
RemoteHost "fingerserver.domain.com"
RemotePort 79
}

On the client, try this script:

449
TCPConnect
int sock = TCPConnect("finger");
str result = "";
// send CR+LF to force finger dump
TCPWrite(sock,BinFromStr("\r\n"));
// receive packets and concatenate
for(;;) {
bool eof;
var ret = TCPRead(sock,eof);
// end of connection?
if (eof) break;
if (sizeof(ret)>0) {
// get data
result = result + BinToStr(ret);
} else {
// wait 0,5 secs
delay(50);
}
}
TCPClose(sock);
Printf("Finger result:<br>%s<br>",result);

See also
See Section 2.4 in REMBO Server Administration Manual for instructions on how
to create a TCP tunnel on the server side.

450
TCPRead
TCPRead — Read bytes from a TCP connection
Synopsis

Defined in
Built-in function.

Function prototype

var TCPRead(int connid, bool eof);

Description
This functions sends a request to the REMBO server to check if there is some data
waiting to be read on the TCP tunnel. If data is available, TCPRead reads the first
1024 bytes of data, or less if less than 1024 bytes is available. If no data is available,
TCPRead returns an empty binary object. The language operating sizeof can be
used on the binary object returned by TCPRead to determine if data is available (i.e.
sizeof(returnedbinary) > 0 if data is available.

Parameter connid is the identifier of an open TCP tunnel, as returned by


TCPConnect.

Parameter eof is used by TCPRead to tell the caller whether the connection is still
open or not. This parameter is modified by TCPRead as follow: if the remote end of
the TCP tunnel has closed the connection, and all data has been read during
previous calls to TCPRead, eof is set to true. eof is set to false in any other
situation (data available or connection still open).

Example
On the server, create a TCP tunnel named finger pointing to a Unix or NT server
setup to answer finger requests:
TCPTunnel finger {
RemoteHost "fingerserver.domain.com"
RemotePort 79
}

On the client, try this script:


int sock = TCPConnect("finger");
str result = "";

451
TCPRead
// send CR+LF to force finger dump
TCPWrite(sock,BinFromStr("\r\n"));
// receive packets and concatenate
for(;;) {
bool eof; // eof value is not used by TCPRead
var ret = TCPRead(sock,eof);
// end of connection?
if (eof) break;
if (sizeof(ret)>0) {
// get data
result = result + BinToStr(ret);
} else {
// wait 0,5 secs
delay(50);
}
}
TCPClose(sock);
Printf("Finger result:<br>%s<br>",result);

See also
See Section 2.4 in REMBO Server Administration Manual for instructions on how
to create a TCP tunnel on the server side.

452
TCPWrite
TCPWrite — Send bytes to a TCP peer
Synopsis

Defined in
Built-in function.

Function prototype

void TCPWrite(int connid, var data);

Description
This functions sends data into a TCP tunnel. The given data must be a binary object
with no more than 1024 bytes.
Parameter connid is the identifier of an open TCP tunnel, as returned by
TCPConnect.

Example
On the server, create a TCP tunnel named finger pointing to a Unix or NT server
setup to answer finger requests:
TCPTunnel finger {
RemoteHost "fingerserver.domain.com"
RemotePort 79
}

On the client, try this script:


int sock = TCPConnect("finger");
str result = "";
// send CR+LF to force finger dump
TCPWrite(sock,BinFromStr("\r\n"));
// receive packets and concatenate
for(;;) {
bool eof; // eof value is not used by TCPRead
var ret = TCPRead(sock,eof);
// end of connection?
if (eof) break;
if (sizeof(ret)>0) {
// get data
result = result + BinToStr(ret);
} else {

453
TCPWrite
// wait 0,5 secs
delay(50);
}
}
TCPClose(sock);
Printf("Finger result:<br>%s<br>",result);

See also
See Section 2.4 in REMBO Server Administration Manual for instructions on how
to create a TCP tunnel on the server side.

454
TCPClose
TCPClose — Close a TCP connection
Synopsis

Defined in
Built-in function.

Function prototype

void TCPClose(void);

Description
This functions closes a TCP tunnel previously setup with a call to TCPConnect.
Parameter connid is the identifier of an open TCP tunnel, as returned by
TCPConnect.

Example
On the server, create a TCP tunnel named finger pointing to a Unix or NT server
setup to answer finger requests:
TCPTunnel finger {
RemoteHost "fingerserver.domain.com"
RemotePort 79
}

On the client, try this script:


int sock = TCPConnect("finger");
str result = "";
// send CR+LF to force finger dump
TCPWrite(sock,BinFromStr("\r\n"));
// receive packets and concatenate
for(;;) {
bool eof; // eof value is not used by TCPRead
var ret = TCPRead(sock,eof);
// end of connection?
if (eof) break;
if (sizeof(ret)>0) {
// get data
result = result + BinToStr(ret);
} else {
// wait 0,5 secs

455
TCPClose
delay(50);
}
}
TCPClose(sock);
Printf("Finger result:<br>%s<br>",result);

See also
See Section 2.4 in REMBO Server Administration Manual for instructions on how
to create a TCP tunnel on the server side.

456
SendMail
SendMail — Send a mail to an arbitrary email address
Synopsis

Defined in
/plugins/sendmail.rbx

Function prototype

void SendMail(str from, str to, str subject, str msg);

Description
This functions sends the message contained in the string msg to the EMail address
to, using from as the originating EMail address. The subject of the EMail is set to
subject.
This function uses the sendmail TCP tunnel to access a SMTP server and deliver
the message. Before using this function, you must setup a TCP tunnel called
sendmail on your server, with a valid SMTP server as the RemoteHost parameter,
and 25 (SMTP port) for RemotePort. For example, if you are using file-based
configuration, you will have to add these lines in your configuration file (before the
first host group):
TCPTunnel sendmail {
RemoteHost "mail.company.com"
RemotePort 25
}

This function is implemented by the /plugins/sendmail.rbx script. To use this


function, you must first execute the sendmail.rbx script with
join(Exec("cache://global/plugins/sendmail.rbx"));

SendMail will raise an exception if an error occur during the delivery of the
message. The irritant field of the exception structure can be used to determine the
exact cause of the error.

457
SendMail
Example
// Get the content of the console window
str msg = LoadTextFile("display://console/body/content/value");
// Send it to sysadmin@company.com
SendMail("rembo@company.com",
"sysadmin@company.com",
"REMBO Console Log", msg);

See also
See Section 2.8.1 in REMBO Client Administration Manual for a detailed
description of mail support in REMBO.

458
SQLOpen
SQLOpen — Open an ODBC session with a database server
Synopsis

Defined in
/plugins/sql.rbx (Enterprise Edition only)

Function prototype

var SQLOpen(str database, str username, str password);

Description
This function initiates a connection to a database server. The first parameter,
database, is the name of the database to connect to. When the ODBC version of
the gateway is used (the default on Windows NT), this corresponds to the name of
the system DSN that points to your database. For the JDBC version of the gateway,
the syntax is driver:[//host/]source. For instance
"mysql://129.194.69.1/inventory" or "odbc:AutoDeploy".

The last two parameters are the username and password to use for connecting to the
database. Leave these parameters empty (empty string, "") if your ODBC data
source is not using authentication.
The variable returned by SQLOpen is a connection identifier. Use this identifier when
calling SQLQuery and SQLClose.
Once open with SQLOpen, the database connection stays open until SQLClose is
called, or if there is no activity during 60 seconds.
Before using this function, you must create a TCP tunnel called ODBC on the server,
and install the TCP to database gateway software provided with your REMBO
server. See Section 2.8.2 in REMBO Client Administration Manual for more
information.

Example
var db = SQLOpen("mybase","","");
// perform a query
str query = Strf(’select * from hosts where mac=\"%s\"’,
NetInfo.MACAddress);
var result = SQLQuery(db, query);
// show result
LogVar(result);

459
SQLOpen

// perform other queries...


// result = SQLQuery(db,...)

// close the connection


SQLClose(db);

See also
See Section 2.8.2 in REMBO Client Administration Manual for a detailed
description of database access in REMBO.
SQLOpenEx for additional options, for instance connecting to ODBC without
creating a system DSN.

460
SQLOpenEx
SQLOpenEx — Open an ODBC session with extra parameters
Synopsis

Defined in
/plugins/sql.rbx (Enterprise Edition only)

Function prototype

var SQLOpenEx(str openstring);

Description
This function initiates a connection to a database server. The parameter
openstring is passed as-is to the database gateway for connecting to the
database.

The easiest way to check that openstring is valid is to have have a


command shell open on the computer where REMBO server is installed and to
use "telnet 127.0.0.1 2020" to converse with the database gateway.
Successful requests to the gateway are acknowledged by a line containing
"//--OK".

Possible values of the openstring are:

• use dsn,user,pass: with the ODBC version of the gateway, connects to an


existing system DSN; user and pass can be omitted, as well as the commas;
• use [descr-string]: with the ODBC version of the gateway, connects to a
database without having a system DSN; the square brackets are required in the
syntax, descr-string is passed as-is to the Windows function
SQLDriverConnect;
• use driver://dbhost/source,user,pass: with the JDBC version of the
gateway, connects to a database; dbhost, user and pass can be omitted;
• reuse can be typed instead of use: for improved performance under heavy loads,
the connection will be shared by all clients connecting to the same database with
the same parameters.

461
SQLOpenEx
The variable returned by SQLOpen is a connection identifier. Use this identifier when
calling SQLQuery and SQLClose.
Once open with SQLOpenEx, the database connection stays open until SQLClose is
called, or if there is no activity during 60 seconds.
Before using this function, you must create a TCP tunnel called ODBC on the server,
and install the TCP to database gateway software provided with your REMBO
server. See Section 2.8.2 in REMBO Client Administration Manual for more
information.

Example

// ODBC, connect to an existing system DSN:


SQLOpenEx("use ExampleDB");
// ODBC, connect to an existing system DSN with security:
SQLOpenEx("use ExampleDB,name,secret");
// ODBC, connect to MS SQL Server without DSN:
str query = Strf("use [DRIVER={SQL Server};SERVER=%s;UID=%s;PWD=%s;DATABASE=%s]
db_hostname,db_userid,db_pwd,db_name);
var dbc = SQLOpenEx(query);
// JDBC, connect to mysql database:
SQLOpenEx("use mysql://192.168.1.72/exampledb,root,secret");
// JDBC, connect to MS SQL database:
str query = Strf("use microsoft:sqlserver://%s:%d;DatabaseName=%s,%s,%s",
db_hostname,db_serverport,db_name,db_userid,db_pwd);
var dbc = SQLOpenEx(query);

// ODBC, connect to an existing system DSN:


SQLOpenEx("reuse ExampleDB");
// ODBC, connect to an existing system DSN with security:
SQLOpenEx("reuse ExampleDB,name,secret");
// ODBC, connect to MS SQL Server without DSN:
str query = Strf("reuse [DRIVER={SQL Server};SERVER=%s;UID=%s;PWD=%s;DATABASE=%
db_hostname,db_userid,db_pwd,db_name);
var dbc = SQLOpenEx(query);
// JDBC, connect to mysql database:
SQLOpenEx("reuse mysql://192.168.1.72/exampledb,root,secret");
// JDBC, connect to MS SQL database:
str query = Strf("reuse microsoft:sqlserver://%s:%d;DatabaseName=%s,%s,%s",
db_hostname,db_serverport,db_name,db_userid,db_pwd);
var dbc = SQLOpenEx(query);

462
SQLOpenEx
See also
See SQLOpen, for simple cases.
Section 2.8.2 in REMBO Client Administration Manual for a detailed description of
database access in REMBO.

463
SQLQuery
SQLQuery — Execute a SQL query on an open ODBC session
Synopsis

Defined in
/plugins/sql.rbx (Enterprise Edition only)

Function prototype

var SQLQuery(var database, str query);

Description
This function executes the given SQL query on the database previously setup with
SQLOpen. The first parameter must be a valid database identifier, as returned by
SQLOpen.

SQLQuery returns the result of the SQL query as a structure, with structure members
names being the name of the corresponding columns in the table.
Any valid SQL query is accepted, including INSERT and UPDATE queries.
SQLQuery raises an exception if an error occur when executing the SQL query. The
irritant field of the exception structure contains information about the cause of
the error.

Example
var db = SQLOpen("mybase","","");
// perform a query
str query = Strf(’select * from hosts where mac=\"%s\"’,
NetInfo.MACAddress);
var result = SQLQuery(db, query);
// show result
LogVar(result);

// perform other queries...


// result = SQLQuery(db,...)

// close the connection


SQLClose(db);

464
SQLQuery
See also
See Section 2.8.2 in REMBO Client Administration Manual for a detailed
description of database access in REMBO.

465
SQLClose
SQLClose — Close an ODBC session
Synopsis

Defined in
/plugins/sql.rbx (Enterprise Edition only)

Function prototype

void SQLClose(var database);

Description
This function closes a database connection previously setup with SQLOpen. The
given parameter must be a valid database identifier, as returned by SQLOpen.

Example
var db = SQLOpen("mybase","","");
// perform a query
str query = Strf(’select * from hosts where mac=\"%s\"’,
NetInfo.MACAddress);
var result = SQLQuery(db, query);
// show result
LogVar(result);

// perform other queries...


// result = SQLQuery(db,...)

// close the connection


SQLClose(db);

See also
See Section 2.8.2 in REMBO Client Administration Manual for a detailed
description of database access in REMBO.

466
SQLQuickQuery
SQLQuickQuery — Execute a SQL query
Synopsis

Defined in
/plugins/sql.rbx (Enterprise Edition only)

Function prototype

var SQLQuickQuery(str database, str username, str password, str


query);

Description
This function is a shortcut to other database access functions. Its implementation is:
var SQLQuickQuery(str database, str username,
str password, str query)
{
var connid = SQLOpen(database,username,password);
var result = SQLQuery(connid,query);
SQLClose(connid);
return result;
}

See also
See Section 2.8.2 in REMBO Client Administration Manual for a detailed
description of database access in REMBO.

467
5.10. Other system primitives

DeviceBlank
DeviceBlank — Blank-erase the content of a device
Synopsis

Defined in
Built-in function.

Function prototype

void DeviceBlank(str devpath);

Description
This function blanks the device specified by devpath. The device is blanked by
writing null bytes (0) on all the device.

Example
DeviceBlank("disk://0:1");

468
DeviceClean
DeviceClean — Quick-format a device with the default filesystem
Synopsis

Defined in
Built-in function.

Function prototype

void DeviceClean(str devpath);

Description
This function is the internal function called by HDClean. It performs a quick-format
on the specified device, using the partition type to determine which filesystem to
use for quick-format.

Example
DeviceClean("disk://0:1");

469
DeviceCleanEx
DeviceCleanEx — Quick-format a device according to filesystem-specific
parameters
Synopsis

Defined in
built-in function.

Function prototype

void DeviceCleanEx(str devpath, var devinfo);

Description
This function formats a partition using information received in the devinfo to
determine filesystem specific parameters, like the number of files to preallocate, or
the location of filesystem special files.
Filesystem specific information is usually retrieved from a filesystem on a separate
partition or from a disk image using DeviceGetInfo. The binary object returned by
DeviceGetInfo must be passed to DeviceCleanEx as is, without any modification.

It is important to use DeviceCleanEx to prepare the target filesystem if you are


restoring an NTFS filesystem from an image with the Synchronize function. This
will ensure that operating system specific features, like security descriptors, are
properly created on the target filesystem.

Example
// clean 0:5 using parameters from 0:1
var dinfo = DeviceGetInfo("disk://0:1");
DeviceCleanEx("disk://0:5",dinfo);

See also
See also DeviceGetInfo and DeviceGetInfo

470
DeviceGetInfo
DeviceGetInfo — Collect filesystem-specific parameters about a device
Synopsis

Defined in
built-in function.

Function prototype

var DeviceGetInfo(str devpath);

Description
This function retrieves filesystem specific information from either a disk partition
(URL starting with disk:// or a disk image (URL starting with arch:// or
diff://). Information returned by DeviceGetInfo is used by DeviceCleanEx to
preserve filesystem specific features when restoring a disk image.

Example
// clean 0:5 using parameters from 0:1
var dinfo = DeviceGetInfo("disk://0:1");
DeviceCleanEx("disk://0:5",dinfo);

See also
See also DeviceCleanEx.

471
DeviceCleanForce
DeviceCleanForce — Quick-format a device with a specified filesystem
Synopsis

Defined in
Built-in function.

Function prototype

void DeviceCleanForce(str devpath, str fstype);

Description
This function is the internal function called by RDClean. It performs a quick-format
on the specified device, using fstype to determine which filesystem to use for
quick-format. This function is useful for devices which have no partitions (and
therefore no partition type to use to determine the filesystem type).

Example
DeviceCleanForce("floppy://0","FAT12");

472
DevicePreAdapt
DevicePreAdapt — Prepare to temporarily resize a partition to a smaller size
Synopsis

Defined in
built-in function.

Function prototype

void DevicePreAdapt(str device, int desiredKB);

Description
This function is used to prepare a disk partition for splitting by ensuring that
allocated data is located at the beginning of the partition, under the desiredKB
size limit (specified in kilobytes). Data located above the limit is automatically
moved under the limit.
When combined with SetPartitions, this function actually splits a partition into
two parts. Note that this function is supported on FAT based filesystems only.

Example
// split a 4GB FAT32 partition into two parts
DevicePreAdapt("disk://0:1",2000000);
SetPrimaryPartitions(0,"FAT32:2000000 FAT32:2000000");
HDClean(0,2);

See also
See also SetPrimaryPartitions.

473
DeviceAdapt
DeviceAdapt — Temporarily resize filesystem structures to a new partition size
Synopsis

Defined in
Built-in function.

Function prototype

void DeviceAdapt(str devpath);

Description
This function temporarily adapts the filesystem on the device specified by
devpath to the actual partition size. No data will be actually moved on the device,
so the function should only be used when there is no used block outside of the new
size of the partition.
The adapted filesystem should only be used temporarily, in the sense that it has not
really been formatted for the adapted size and may therefore be suboptimal and
even fail some integrity checks if scanned in details. However, it is safe enough to
access the adapted filesystem from an operating system, for reading and writing.
See the example below for a typical use of this function.
Note that it is usually safer not to adapt a partition to less than 60% of its original
size. This is specially true for the NTFS filesystem, that may otherwise get corrupt.

Example
// Create a large partition
SetPrimaryPartitions(0, "FAT32:10000000")
DeviceClean("disk://0:1");
// Adapt it to create a temporary 2GB cache partition
SetPrimaryPartitions(0, "FAT32:8000000")
DeviceAdapt("disk://0:1");
// Install an OS using the cache partition for the multicast download
Synchronize("cache://global/my-os.img","disk://0:1","b")
// Grow the partition back to its normal size
SetPrimaryPartitions(0, "FAT32:10000000")
DeviceAdapt("disk://0:1");

474
DeviceClose
DeviceClose — Flush and release ressources associated to an open filesystem
Synopsis

Defined in
Built-in function.

Function prototype

void DeviceClose(str devpath);

Description
This function closes the device specified by devpath. All unsaved information is
flushed first to the device, then all ressources associated to the device are freed.
This function is specially useful to handle removable devices, but can also be used
if a device needs to be reopened using another filesystem type. For instance, you
may write raw data to a device first and then reopen the device later to access it
using the adequate filesystem handler.

Example
DeviceClose("floppy://0");

475
DeviceCheck
DeviceCheck — Detect and optionally fix filesystem corruptions
Synopsis

Defined in
Built-in function.

Function prototype

var DeviceCheck(str devpath, bool fixit, bool flush);

Description
DeviceCheck checks and optionally fixes the filesystem structure on a device (aka
ScanDisk). The function returns a structure describing the number of recoverable
blocks (or clusters), inodes and directory entries.
The fixes are only applied if the a parameter fixit is true. As no user interaction
is expected, the filesystem integrity is recovered by a destructive method: all blocks
not allocated in a properly built file are freed, and all incorrect directory entries are
deleted. This ensures a safe filesystem state even in case of system crash, but may
lead to loss of data for all files that were not properly flushed at the time the
computer was stopped.
If fixes are applied, this function clears the filesystem dirty flag, and thus avoid the
automatic start of the operating system own ScanDisk or fsck program.
If the call to DeviceCheck is followed by a call to Synchronize or a similar
filesystem-intensive function, performance can be increased by delaying the flush to
disk (which will then be done automatically by Synchronize).
Currently, this function is only supported on FAT-based filesystems.

Example
When using self-healing on a partition, it is safer first to check and fix possible
filesystem corruptions in the target partition:
DeviceCheck("disk://0:1/", true, false);
Synchronize("cache://global/myimage","disk://0:1/","b");

476
DeviceCheck
See also
See also HDCheck.

477
DeviceSetDirty
DeviceSetDirty — Change the dirty flag of a device
Synopsis

Defined in
Built-in function.

Function prototype

void DeviceSetDirty(str devpath, bool isDirty);

Description
DeviceSetDirty changes the so-called dirty flag on a filesystem, so that the
operating system trusts or do not trust the filesystem stability. This function is
currently only supported on NTFS.

Example
To force a filesystem check on NTFS by the operating system, use the following
code:
DeviceSetDirty("disk://0:1", true);

See also
See also DeviceCheck and DeviceInfo.

478
DeviceBoot
DeviceBoot — Boot from a specified device
Synopsis

Defined in
Built-in function.

Function prototype

void DeviceBoot(str devpath, bool unloadpxe);

Description
This is the internal function used by HDBoot and FloppyBoot. This function
gracefully shutdowns REMBO and boots on the specified device.
If parameter unloadpxe is false, the UNDI part of the PXE bootrom is kept in the
memory. Otherwise, all the PXE bootrom is removed from the memory before
booting (default behaviour used in HDBoot and FloppyBoot.

Example
DeviceBoot("floppy://0",true);

479
FileBoot
FileBoot — Boot using the content of a file
Synopsis

Defined in
Built-in function.

Function prototype

void FileBoot(str filename, int devicenum, bool unloadpxe);

Description
This function removes REMBO from the main memory and uses the content of the
file filename to continue the boot process.
Only the first 512 bytes of the given file are loaded into memory. The file must
contain a valid bootsector as the first 512 bytes, with a valid signature (aa55h) at the
end of the bootsector.
The parameter devicenum is used by FileBoot to set the value of the drive
parameter when calling the bootsector stored in the file filename. If the file
contains a bootsector extracted from a floppy disk, use 0 as the value for
devicenum. If the file contains a bootsector extracted from a hard disk, use the
value 0x80 instead.
If parameter unloadpxe is false, the UNDI part of the PXE bootrom is kept in the
memory. Otherwise, all the PXE bootrom is removed from the memory before
booting (default behaviour used in HDBoot and FloppyBoot.

Example
FileBoot("cache://global/backuped-mbr",0x80,true);

480
DeviceInfo
DeviceInfo — Gather general information about a device
Synopsis

Defined in
Built-in function.

Function prototype

var DeviceInfo(str devpath);

Description
This functions retrieves information on a block device specified by the parameter
devpath. Blocks devices under REMBO are disks, floppy, ramdisks and loopback
devices.
You can also use this function on a hard-disk image to retrieve information on the
filesystem stored in the image (e.g. the number of boot sectors can be used to
determine if the image is a BIGDOS or FAT32 image).
On disks, devices actually correspond to partitions (e.g. disk://0:1 is the first
partition of the hard disk 0).
A structure containing the following members is returned:

• int bootSectSize: size in bytes of the boot sector area;


• int totalSize: size of the device in kilobytes;
• bool dirtyfs: this value is set to true if the filesystem on the device is in an
unstable state (dirty);
• str fstype: this value is set to the filesystem identifier for the filesystem
detected on the device. You can use this field to detect the filesystem on a floppy
or on a partition with an invalid or unknown partition identifier (hidden partition).

Example
var di = DeviceInfo("disk://0:1");
if (di.dirtyfs) {
Log("Filesystem dirty. Cleaning in progress...<br>");
HDClean(0,1); // quick-format

481
DeviceInfo
}

482
DeviceAllocInfo
DeviceAllocInfo — Gather allocation information about a device
Synopsis

Defined in
Built-in function.

Function prototype

var DeviceAllocInfo(str devpath);

Description
This functions retrieves allocation information on device specified by the parameter
devpath, such as the number of allocated and free blocks on the device.
On disks, devices actually correspond to partitions (e.g. disk://0:1 is the first
partition of the hard disk 0).
A structure containing the following members is returned:

• int blockSize: size in bytes of allocation units (blocks or clusters);


• int usedBlocks: number of used blocks on the device;
• int freeBlocks: number of remaining free blocks on the device.

Example
var dai = DeviceAllocInfo("disk://0:1");
if (filesize > dai.blockSize * dai.freeBlocks)
Log("Not enough free space to store this file, sorry<br>");

483
DeviceGetFsType
DeviceGetFsType — Return the partition type required by a given device
Synopsis

Defined in
Built-in function.

Function prototype

str DeviceGetFsType(str path);

Description
DeviceGetFsType returns the filesystem identifier for the path given as parameter.
This function is used to determine filesystem type when the partition type is not
explicit. For example, a DIAGNOSTICS partition can host a FAT12 or a FAT16
filesystem.
The returned string is one of the following identifiers:

• NTFS
• FAT12
• FAT16
• FAT32
• EXT2 (linux)
• LINUX-SWAP
• EXT (extended partition)
• TEMPFS (REMBO cache partition)

Example
// run DeviceCheck on FAT only
str fs = DeviceGetFSType("disk://0:1");
if (StrMatch(fs,"FAT*"))
DeviceCheck(fs,true,true);

484
WriteOfflineCode
WriteOfflineCode — Write an offline mode Rembo boot sector to a device
Synopsis

Defined in
Built-in function.

Function prototype

void WriteOfflineCode(str devicepath, bool adminmode, bool autoboot);

Description
This is the internal function used by SetOfflineMode. This function can write on
any device a boot sector that is able to start REMBO in off-line mode.
The parameters adminmode and autoboot correspond to the boot flags that can
be specified on the server when REMBO starts with network connectivity. The first
one determines wether REMBO will start with administrator priviledges, while the
other one specifies whether REMBO should reboot or not in case of fatal internal
error.

See also
See also SetOfflineMode.

485
DevReadBootSects
DevReadBootSects — Read boot sectors on an arbitrary filesystem
Synopsis

Defined in
Built-in function.

Function prototype

var DevReadBootSects(str devicepath);

Description
This function can be used to read the boot sector of an arbitrary filesystem. For
example, it can be used in conjunction with DevWriteBootSects to backup and
restore the Master Boot Record of the primary hard disk.

Example
// Read MBR
var bsect = DevReadBootSects("disk://0:0");
// Save MBR on server
SaveFile(bsect,"cache://host/mbr-backup");

486
DevWriteBootSects
DevWriteBootSects — Write boot sectors on an arbitrary filesystem
Synopsis

Defined in
Built-in function.

Function prototype

void DevWriteBootSects(str devicepath, var bsect);

Description
This function can be used to write the boot sector of an arbitrary filesystem.
Filesystem specific information contained in the bootsector are not written (i.e.
REMBO preserves some fields depending on the partition size, hard disk number,
etc...).
This function can be used in conjunction with DevReadBootSects to backup and
restore the Master Boot Record of the primary hard disk.

Example
if (FileExists("cache://host/mbr-backup")) {
// Load MBR
var bsect = LoadFile("cache://global/mbr-backup");
// Write it
DevWriteBootSects("disk://0:0",bsect);
}

487
DevReadLabel
DevReadLabel — Read the label associated with a filesystem
Synopsis

Defined in
Built-in function.

Function prototype

str DevReadLabel(str devicepath);

Description
This function can be used to read the label associated with a filesystem. Not all
filesystems support this function. See also DevWriteLabel.
Note that label is automatically backuped during a Synchronize operation. During
hard disk image restoration, label is restored on disk only when the "b" flag is set as
the last parameter of Synchronize.

Example
// Read label
str label = DevReadLabel("disk://0:1");
Printf("The label for the first partition is %s<br>",label);

488
DevWriteLabel
DevWriteLabel — Modify the label associated with a filesystem
Synopsis

Defined in
Built-in function.

Function prototype

void DevWriteLabel(str devicepath, str newlabel);

Description
This function sets the label on the device devicepath to newlabel. Note that
not all filesystems support this call.
Note that label is automatically backuped during a Synchronize operation. During
hard disk image restoration, label is restored on disk only when the "b" flag is set as
the last parameter of Synchronize.

Example
// Read label
str label = DevReadLabel("disk://0:1");
Printf("The label for the first partition is %s<br>",label);
// Modify the label
label = "NEW"+label;
DevWriteLabel("disk://0:1",label);

489
DevReadUUID
DevReadUUID — Read the UUID value associated with a filesystem
Synopsis

Defined in
Built-in function.

Function prototype

var DevReadUUID(str devicepath);

Description
This function can be used to read the UUID (unique identifier) associated with a
filesystem. This function call is not supported by all filesystems (it is currently
supported by FAT filesystems only).
Note that the UUID for FAT filesystem is not backuped nor restored when cloning
hard disk partitions with Synchronize. When a new partition is restored (i.e. the
partition is first formatted before restoring files with Synchronize), a randomly
choosen UUID is stored in the partition. If you want to restore the same UUID as on
the reference client, you should use DevReadUUID and DevWriteUUID to explicitely
backup and restore the UUID.

Example
// Backup partition
Synchronize("disk://0:1","cache://global/fatimage.img",""):
// Backup UUID
var uuid = DevReadUUID("disk://0:1");
SaveFile(uuid,"cache://global/fatimage.uuid");

490
DevWriteUUID
DevWriteUUID — Modify the UUID value associated with a filesystem
Synopsis

Defined in
Built-in function.

Function prototype

void DevWriteUUID(str devicepath, var newuuid);

Description
This function modifies the UUID (unique identifier) associated with a filesystem.
This function call is not supported by all filesystems (it is currently supported by
FAT filesystems only).
Note that the UUID for FAT filesystem is not backuped nor restored when cloning
hard disk partitions with Synchronize. When a new partition is restored (i.e. the
partition is first formatted before restoring files with Synchronize), a randomly
choosen UUID is stored in the partition. If you want to restore the same UUID as on
the reference client, you should use DevReadUUID and DevWriteUUID to explicitely
backup and restore the UUID.

Example
// Restore image
HDClean(0,1);
Synchronize("cache://global/fatimage","disk://0:1","b");
// Get UUID from file
var uuid = LoadFile("cache://global/fatimage.uuid");
// Write to disk
DevWriteUUID("disk://0:1",uuid);

491
InitDownload
InitDownload — Setup a multicast download process
Synopsis

Defined in
Built-in function.

Function prototype

var InitDownload(str remotepath, str localpath, bool ismd5);

Description
This function initiates a multicast file download, as described for Download. The
value returned is a binary object encapsulating the state of the operation, and that
should be given as argument to MoreDownload to resume the operation.

Example
The code below performs a multicast download similar to the function Download,
but using the low-level functions described in this section:
var downstate = InitDownload(remotefile, localfile, ismd5);
int counter;
str message;

OpenProgressBar("download","Downloading...");
while((counter = MoreDownload(downstate)) < 100) {
SetProgressBar("download", counter);
if((message = InfoDownload(downstate)) != "")
SetProgressInfo("download", message);
}
CloseProgressBar("download");

492
InitUDownload
InitUDownload — Setup an unicast download process
Synopsis

Defined in
Built-in function.

Function prototype

var InitUDownload(str remotepath, str localpath, bool ismd5);

Description
This function initiates an unicast file download, similarly to what the Download
would have done in multicast. The value returned is a binary object encapsulating
the state of the operation, and that should be given as argument to MoreDownload to
resume the operation.

Example
The code below performs an unicast download:
var downstate = InitUDownload(remotefile, localfile, ismd5);
int counter;
str message;

OpenProgressBar("download","Downloading...");
while((counter = MoreDownload(downstate)) < 100) {
SetProgressBar("download", counter);
if((message = InfoDownload(downstate)) != "")
SetProgressInfo("download", message);
}
CloseProgressBar("download");

493
MoreDownload
MoreDownload — Continue a download process
Synopsis

Defined in
Built-in function.

Function prototype

int MoreDownload(var downstate);

Description
This function resumes for at least half a second the download operation initiated
earlier with InitDownload and whose state is stored in the the binary object
downstate.
The return value is a number between 0 and 100 representing the overall progress of
the operation, in percents.

Example
See the example under InitDownload.

494
InfoDownload
InfoDownload — Get information about the progress of a download
Synopsis

Defined in
Built-in function.

Function prototype

str InfoDownload(var downstate);

Description
This function returns a text describing any change in the status of the running
download operation stored in the binary object downstate. If the status has not
changed during the last MoreDownload operation, an empty string is returned.

Example
See the example under InitDownload.

495
DownloadResult
DownloadResult — Retrieve the result of a memory download
Synopsis

Defined in
Built-in function.

Function prototype

var DownloadResult(var downstate);

Description
This function returns a binary object containing the result of a memory download
(not going through the cache partition), from a completed download state. Note that
in order to initiate a memory download, the local file argument of InitDownload
must be empty.

Example
The code below performs a multicast download in memory:
var downstate = InitDownload(remotefile, "", false);
int counter;
str message;

OpenProgressBar("download","Downloading...");
while((counter = MoreDownload(downstate)) < 100) {
SetProgressBar("download", counter);
if((message = InfoDownload(downstate)) != "")
SetProgressInfo("download", message);
}
CloseProgressBar("download");
var result = DownloadResult(downstate);

496
InitBatchTransfer
InitBatchTransfer — Setup a multiple file transfer process
Synopsis

Defined in
Built-in function.

Function prototype

var InitBatchTransfer(str remoteDev, str batchId, int waitHosts, int


waitSec);

Description
This function initiates a multiple file transfer, as described for BatchTransfer. The
value returned is a binary object encapsulating the state of the operation, and that
should be given as argument to AddToBatchTransfer to schedule file transfers and
to MoreBatchTransfer to resume the operation.
The remoteDev parameter specifies the device from which all files will be
copied. The three other parameters are the synchronization parameters when
running a multicast download. See BatchTransfer for a detailled explanation.

Example
The code below performs a batch transfer similar to the function BatchTransfer,
but using the low-level functions described in this section:
var downstate;
int counter;
str message;

downstate = InitBatchTransfer(serverroot, batchid,


waitClients, waitSec);

for(int i = 0; i < sizeof(files); i++) {


if(files[i][2] & 1 != 0) // transfer the file itself
AddToBatchTransfer(downstate,
files[i][0],
files[i][1], 1);
if(files[i][2] & 2 != 0) // transfer the MD5 file
AddToBatchTransfer(downstate,
files[i][0]+(str)srcmd5,
files[i][1]+".md5", 2);
if(files[i][2] & 4 != 0) // transfer the archive shared files
AddToBatchTransfer(downstate,

497
InitBatchTransfer
files[i][0],
files[i][1], 4);
}

OpenProgressBar("transfer", "Transfering files...");


while((counter = MoreBatchTransfer(downstate)) < 100) {
SetProgressBar("transfer", counter);
if((message = InfoBatchTransfer(downstate)) != "")
SetProgressInfo("transfer", message);
}
CloseProgressBar("transfer");

See also
See also BatchTransfer.

498
AddToBatchTransfer
AddToBatchTransfer — Add a file to a multiple file transfer process
Synopsis

Defined in
Built-in function.

Function prototype

void AddToBatchTransfer(var downstate, str remotefile, str localfile,


int mode);

Description
This function schedules the transfer of the file pointed by remotefile to the
destination localfile. The mode parameter can be either 1, 2 or 4, depending
on whether the request is to transfer the file itself, the MD5 subfile or the related
shared files respectively.

Example
See the example under InitBatchTransfer.

See also
See also BatchTransfer.

499
MoreBatchTransfer
MoreBatchTransfer — Continue a multiple file transfer process
Synopsis

Defined in
Built-in function.

Function prototype

int MoreBatchTransfer(var downstate);

Description
This function resumes for at least half a second the transfer operation initiated
earlier with InitBatchTransfer and whose state is stored in the the binary object
downstate.
The return value is a number between 0 and 100 representing the overall progress of
the operation, in percents.

Example
See the example under InitBatchTransfer.

See also
See also BatchTransfer.

500
InfoBatchTransfer
InfoBatchTransfer — Get information about the progress of a transfer
process
Synopsis

Defined in
Built-in function.

Function prototype

str InfoBatchTransfer(var downstate);

Description
This function returns a text describing any change in the status of the running
download operation stored in the binary object downstate. If the status has not
changed during the last MoreDownload operation, an empty string is returned.

Example
See the example under InitBatchTransfer.

See also
See also BatchTransfer.

501
InitSynchro
InitSynchro — Setup a filesystem synchronization
Synopsis

Defined in
Built-in function.

Function prototype

var InitSynchro(str srcpath, str targetpath, str mode);

Description
This function initiates a synchronization operation between two filesystems, as
described for Synchronize. The value returned is a binary object encapsulating the
state of the operation, and that should be given as argument to MoreSynchro to
resume the operation.

Example
The code below performs a synchronization similar to the function Synchronize
using the low-level functions described in this section:
var syncstate = InitSynchro(source, target, mode);
int counter;
str message;

OpenProgressBar("synchro","Synchronizing...");
while((counter = MoreSynchro(syncstate)) < 100) {
SetProgressBar("synchro", counter);
if((message = InfoSynchro(syncstate)) != "")
SetProgressInfo("synchro", message);
}
CloseProgressBar("synchro");
Print("Synchronization completed:");
LogVar(SynchroStats(syncstate));

502
MoreSynchro
MoreSynchro — Continue a filesystem synchronization
Synopsis

Defined in
Built-in function.

Function prototype

int MoreSynchro(var syncstate);

Description
This function resumes for at least half a second the synchronization operation
initiated earlier with InitSynchro and whose state is stored in the the binary object
syncstate.
The return value is a number between 0 and 100 representing the overall progress of
the operation, in percents.

Example
See the example under InitSynchro.

503
InfoSynchro
InfoSynchro — Get informations about the progress of a filesystem
synchronization
Synopsis

Defined in
Built-in function.

Function prototype

str InfoSynchro(var syncstate);

Description
This function returns a text describing any change in the status of the running
synchronize operation stored in the binary object syncstate. If the status has not
changed during the last MoreSynchro operation, an empty string is returned.

Example
See the example under InitSynchro.

504
SynchroStats
SynchroStats — Get summary informations about a filesystem synchronization
Synopsis

Defined in
Built-in function.

Function prototype

var SynchroStats(var syncstate);

Description
This function returns a structure including several counters, summarizing the
actions performed during a synchronize operation. The structure members are:

• skipped: the number of files that were skipped by the operation because they
were unreadable;
• added: the number of files added to the destination filesystem;
• deleted: the number of files removed from the destination filesystem;
• modified: the number of files updated on the destination filesystem.

Example
See the example under InitSynchro.

505
ApplyTextDiff
ApplyTextDiff — Apply an edited textual difference to a virtual image
Synopsis

Defined in
Built-in function.

Function prototype

var ApplyTextDiff(var textbuffer, int startpos, int stoppos, str


modifpath, str virtualpath);

Description
This function is used internally by MakeDiffFromText to virtually modify a
differential image according to an edited text log.
The textbuffer should be a textual difference list, as originally produced by the
Synchronize function, but loaded as a binary file. The start and stop
parameters are absolute offset in the list of the section to consider. The
modifpath should point to the location where the modified files are available
(typically on the hard-disk), while the virtualpath should point to a virtual
image setup on the reference image. The function will update this virtual image by
setting links to the modified image path.

Example
// 1. Create a text diff
OpenArchive("ref", "cache://global/refimage");
Synchronize("disk://0:1","arch://ref",
"(cache://global/changes.txt)>");
// 2. Edit the changes in the text file
...
// 3. Create the differential image
var difftxt = LoadFile("cache://global/changes.txt");
CreateVirtualImage("tmp","arch://ref");
ApplyTextDiff(difftxt,0,sizeof(difftxt),
"disk://0:1", "link://tmp");
Synchronize("link://tmp","arch://ref",
">cache://global/changes.diff");
// 4. Free ressources
FreeVirtualImage("tmp");
CloseArchive("ref");

506
ApplyTextDiff

See also
See also MakeDiffFromText, LinkTree, UnlinkTree.

507
InitRemboFloppy
InitRemboFloppy — Setup cache-to-floppy cloning process
Synopsis

Defined in
Built-in function.

Function prototype

var InitRemboFloppy(str destpath, bool adminmode, bool autoboot);

Description
This function starts saving the content of REMBO cache partition in a bootable
floppy image, that can later be written to a floppy disk with RestoreFloppyImage to
run REMBO in stand-alone mode.
Before creating a floppy image using this function, you should ensure that the cache
partition contains all necessary ressources needed by your scripts to run without
network connectivity. To check this, call SetOfflineMode start REMBO in off-line
mode and ensure that the configuration run smoothly.
InitRemboFloppy creates a 1.44MB image file and stores this image in the file
specified by destpath. Typically, the destination path is somewhere under
cache://global/fdimages, so that it is uploaded to the server using the fast upload
protocol.
If the content of the cache partition does not fit on a floppy, an exception will be
thrown to indicate that there is not enough space on the floppy device. To reduce the
size of the cache partition (and the resulting floppy image), clean the cache partition
and run REMBO using only the functions and files that you would use when
running with the floppy.
The two parameters adminmode and autoboot correspond to the boot flags that
can be specified on the server when REMBO starts with network connectivity. The
first one determines whether the floppy version of REMBO will start with
administrator priviledges (extended start menu), while the other one specifies
whether REMBO should reboot or not in case of fatal error.

Example
var clonestate = InitRemboFloppy("cache://global/fdimages/rembooot",true,false)
while(MoreRemboClone(clonestate) < 100);

508
InitRemboFloppy
RestoreFloppyImage("cache://global/fdimages/remboot");

509
InitRemboCDRom
InitRemboCDRom — Setup cache-to-cdrom cloning process
Synopsis

Defined in
Built-in function.

Function prototype

var InitRemboCDRom(str destpath, bool adminmode, bool autoboot);

Description
This function starts saving the content of REMBO cache partition in a bootable ISO
CD-Rom image, that can later be written to a CD-Rom in order to get a stand-alone
version of REMBO.
Before creating an ISO image using this function, you should ensure that the cache
partition contains all necessary ressources needed by your scripts to run without
network connectivity. To check this, call SetOfflineMode start REMBO in off-line
mode and ensure that the configuration run smoothly.
The resulting ISO Image file will be created at the destpath specified as
argument, and should be at least as big as the sum of all files used by the scripts
(including the compressed hard-disk images). Typically, the destination path is
somewhere under cache://global, so that it is uploaded to the server using the fast
upload protocol.
The parameters adminmode and autoboot correspond to the boot flags that can
be specified on the server when REMBO starts with network connectivity. The first
one determines whether the CD-Rom version of REMBO will start with
administrator priviledges, while the other one specifies whether REMBO should
reboot or not in case of fatal internal error.

Example
var clonestate = InitRemboCDRom("cache://global/isoimage",true,false);
while(MoreRemboClone(clonestate) < 100);

510
InitRemboCDRom
See also
See also Section 2.7.2 in REMBO Client Administration Manual.

511
MoreRemboClone
MoreRemboClone — Continue a cache cloning process
Synopsis

Defined in
Built-in function.

Function prototype

int MoreRemboClone(var clonestate);

Description
This function resumes a REMBO self-cloning operation initiated earlier with
InitRemboFloppy or InitRemboCDRom and whose state is stored in the the binary
object clonestate.
The return value is a number between 0 and 100 representing the overall progress of
the operation, in percents.

Example
See the examples under InitRemboFloppy and InitRemboCDRom.

512
BuildFileIndex
BuildFileIndex — Build an index of server files
Synopsis

Defined in
Built-in function.

Function prototype

void BuildFileIndex(str basedir, str pattern, str idxname);

Description
This function creates an archive listing all files in the directory tree pointed by
basedir and matching the specified globbing pattern. This index can the be
searched on the client, without generating poorly scalable search queries on the
network filesyste,
The resulting index has the format of a REMBO archive, and is generated into the
file pointed by idxname. The file can be opened using OpenArchive, and has the
same directory structure as present on the server, except that directories where no
file matching the given pattern have been found are not included in the index. The
file timestamp are as on the server. The only information that is missing is the file
size, as all files in the index have a null size.

Example
BuildFileIndex("net://global","*.img","net://global/images.idx");
OpenArchive("idx","cache://global/images.idx");
FileMan("arch://idx");
CloseArchive("idx");

513
GUnzip
GUnzip — Uncompress a GZIP binary buffer
Synopsis

Defined in
Built-in function.

Function prototype

var GUnzip(var buffer, int pos, int len);

Description
This function uncompressed information contained in buffer, starting at byte
offset pos for len compressed bytes. The buffer must have been compressed with
the GZIP compression protocol, as used by the gzip command under Linux. The
uncompressed output is returned as a binary buffer.
This function can be used to uncompress a Linux initial ramdisk in order to modify
the ramdisk before starting the kernel. See the example for more information.

Example
// Download kernel & initrd
var krn = DownloadFile("net://global/kernel");
var ird = DownloadFile("net://global/initrd.gz");
// Uncompress initrd
var newird = GUnzip(ird,0,sizeof(ird));
// Create a loopback device on initrd
// and add a text file
CreateLoopback(0,"var://newird/newird",0,sizeof(newird));
CreateTextFile("loop://0/test.cfg","test");
CloseLoopback(0);
// Boot
LinuxBootEx(krn,newird,"root=/dev/ram");

See also
See also LinuxBootEx, CreateLoopback, DownloadFile and var URLs.

514
Rembo-C functions index Generate a sound using the PC
speaker
AddIniSection
BinCreate
Add a new section in an .ini
Create a binary object
structure
BinEFind
AddIniValue
Find a binary object in another
Add a new value in an .ini
binary object (extended
structure
version)
AddRemoteConsole (RConsole)
BinFill
Allow the connection of a
Fill a binary object with a
remote console
repeated byte
AddToBatchTransfer
BinFromHex (FromHex)
Add a file to a multiple file
transfer process Build a binary object from its
hexadecimal representation
AddToRootMenu
Add an entry to the root menu BinFromInt
ApplyDiff Build a binary object encoding
a number
Apply a complete differential
image to a filesystem BinFromStr
ApplySID Build a binary object encoding
Set SID information on an a string
opened NTFS filesystem BinGetBin
ApplyStyle Extract a subrange from a
Apply a stylesheet to a binary object
window BinGetInt
ApplyTextDiff Extract a signed number from
Apply an edited textual a binary object
difference to a virtual image BinGetLine
ArchiveType Extract a line of text from a
Read the first bytes of a file to binary object
detect if it is an archive BinGetNextLinePtr
AuthUser (AuthUser) Get the offset of the next line
Authenticate a user against a of text
preset domain BinGetStr
AuthUserEx (AuthUserEx) Extract a string from a binary
Authenticate a user against an object
arbitrary domain BinGetUInt
AutoResizeWindow Extract an unsigned number
Automatically resize a from a binary object
window BinReplace
BatchTransfer Find and replace a binary
Run a multiple file transfer sequence in a binary object
Beep BinSetBin

515
Rembo-C functions index
Patch a binary object with BuildIniFile
another binary object Build an .ini content into a
BinSetInt string for saving
Patch a binary object with a BuildUnquotedIniFile
number Build an .ini content, without
BinSetRandom quoting values
Fill a binary object with CachedFileStat
random data Retrieve the status of a file
BinSetStr stored in the cache partition
Patch a binary object with a ChDir
string Change the default working
BinToHex (ToHex) directory
Convert a binary object to its ClearProtectedPartitions
hexadecimal representation Remove all protected
BinToInt partitions by removing the
Convert a binary buffer to an BEER sector
integer CloseArchDevice
BinToStr Close an archive opened with
Convert a binary object to a OpenArchDevice
string CloseArchive
BIOSBoot Close a previously opened
Resume the BIOS boot server archive
process CloseDiff
BlowFishDecrypt Close a previously opened
Decrypt a binary block using local archive
Blowfish CloseLoopback
BlowFishEncrypt Close loopback device
Crypt a binary block using CloseProgressBar
Blowfish Close progress dialog
Browse CloseRegistry
Function called to browse an Close a Windows NT registry
arbitrary file edition session
BuildDiskImage CloseShared
Build a compressed image of Manually close the shared
a disk partition files repository
BuildFileIndex CloseWindow
Build an index of server files Close a window
BuildFileSelect CMOSRead
Build an HTML panel for Read data from the CMOS
choosing a file memory
BuildFloppyImage CMOSWrite
Save the image of a floppy Write data to the CMOS
disk to a raw file memory

516
Rembo-C functions index
CodePage (LoadCodePage) CreateUTF8File
Change the active codepage Create an UTF8 file
CompactShared CreateVirtualImage
Free unused space Create a new virtual disk
preallocated for the shared image
repository DateFromInt
CopyCache Retrieve the string
Preload a cache partition representation of a numerical
CopyFile (FileCopy) date
Copy any kind of file DeepCopy
CopyTree Recursively duplicate a
Recursively copy a directory structured variable
and its content DeepFreeze
CreateBinaryFile (SaveFile) Recursively protect a
Create a binary file structured variable
CreateDir (MkDir) DefaultExceptionHandler
Create a new directory Default exception handler
CreateHexFile DescribePartitions
Create a text file containing Build a list of partitions from
the hex string of a binary an array
buffer DeviceAdapt
CreateLoopback Temporarily resize filesystem
Create a new loopback device structures to a new partition
on a file size
CreateMultiUniFile DeviceAllocInfo
Create a multi-valued unicode Gather allocation information
file about a device
CreateRamDisk DeviceBlank
Allocate a ramdisk Blank-erase the content of a
CreateRemboCDRom device
Create a bootable ISO DeviceBoot
CD-Rom image of Rembo Boot from a specified device
CreateRemboFloppy DeviceCheck
Create a bootable floppy Detect and optionally fix
image of Rembo filesystem corruptions
CreateStrFile DeviceClean
Create a file containing a Quick-format a device with
Rembo unicode string the default filesystem
CreateTextFile (SaveText) DeviceCleanEx
Create a text file (codepage Quick-format a device
encoded) according to
CreateUnicodeFile filesystem-specific parameters
Create an unicode file DeviceCleanForce

517
Rembo-C functions index
Quick-format a device with a Compare two .ini files and
specified filesystem extract differences
DeviceClose DMIBIOSInfo
Flush and release ressources Retrieve DMI information
associated to an open about the BIOS
filesystem DMIMemoryInfo
DeviceCount Retrieve DMI information
Answer the number of about the memory
connected devices DMIOnBoardDev
DeviceGetFsType Retrieve the list of on board
Return the partition type devices (DMI)
required by a given device DMIProcessorInfo
DeviceGetInfo Retrieve DMI information
Collect filesystem-specific about the processor
parameters about a device DMISystemInfo
DeviceInfo Retrieve DMI information
Gather general information about the processor
about a device Download
DevicePreAdapt Download a file from the
Prepare to temporarily resize a server with the MCAST
partition to a smaller size protocol
DeviceSetDirty DownloadFile
Change the dirty flag of a Download a file in multicast
device without using the hard-disk
DevReadBootSects DownloadResult
Read boot sectors on an Retrieve the result of a
arbitrary filesystem memory download
DevReadLabel EnumKeys
Read the label associated with Retrieve the array of possible
a filesystem values for an enumerated
DevReadUUID variable
Read the UUID value Eval
associated with a filesystem Evaluate a Rembo-C
DevWriteBootSects expression in a new thread
Write boot sectors on an Exec
arbitrary filesystem Load and execute a Rembo-C
DevWriteLabel script in a new thread
Modify the label associated Export
with a filesystem Make a variable persistent
DevWriteUUID FatalError
Modify the UUID value Trigger a fatal error, stop
associated with a filesystem REMBO
DiffIniFile FDisk

518
Rembo-C functions index
Open a partition table editor FileSize
window Answer the file size in bytes
FileBoot FileSkip
Boot using the content of a file Move the file pointer to a
FileChooser relative position
Open a file chooser dialog FileStat
FileClose Answer file status
Close an open file informations
FileDiff FileTell
Compare two text files and Answer the current file pointer
extract the differences absolute position
FileDownloadInProgress FileTest
Answer true iff there is an Perform a full read test on a
ongoing MCAST download device
for a specified file FileWrite
FileExists Write a binary object to a file
Test for the existence of a file FileWriteFrom
or directory Copy the content of a file to
FileGetAttribute another
Retrieve filesystem-specific FindExtendedPartition
file attributes Retrieve the index of the
FileLink extended partition
Create a hard-link FitPartitions
FileMan Expand wildcards in a list of
Open a file manager window partitions
FileOpen FloppyBoot
Open a file Let the computer boot on a
FilePatch floppy disk
Patch a text file with FlushAll (Flush)
previously extracted Commit to disk all cached
differences data
FileRead FreeRamDisk
Read a binary object from a Deallocate a ramdisk
file FreeVirtualImage
FileSeek Dismiss a virtual disk image
Move the file pointer to an GarbageCollect
absolute position Force memory garbage
FileSetAttribute collection
Change filesystem-specific file GeneratePassword
attributes Generate a random password
FileSetSize GenerateSID
Resize a file to the specified Generate a new random SID
size based on an existing SID

519
Rembo-C functions index
GetBEER Retrieve information about all
Retrieve the protected network adapters
partitions global parameters GetNICType
GetBEEREntry Retrieve PCI information
Retrieve the parameters of a about the PXE adapter
given protected partition GetPCICards
GetBootablePartition Retrieve the array of PCI cards
Retrieve the list of primary GetPnPCards
partitions Retrieve the array of PnP
GetDMIStrings cards
Retrieve strings associated GetPrimaryPartitions
with a DMI table Retrieve the list of primary
GetDMITables partitions
Retrieve a SMBIOS DMI GetPrimaryPartitionsEx
table Retrieves the list of primary
GetExtDiskInfo partitions, with more details
Get extended information GetProtectedPartitions
about a BIOS disk Retrieve the list of protected
GetIniStruct partitions
Retrieve a section from an .ini GetServerInfo
structure Retrieve server information
GetIniValue GetSharedSize
Retrieve a value from an .ini Get the total size of shared
structure files required by an archive
GetLock GetSIDFromFile
Acquire a named lock on the Extract a SID from a file
server for synchronization GetSIDFromRegistry
GetLogicalPartitions Extract a SID from a registry
Retrieve the list of logical file
partitions GetSystemDevices
GetLogicalPartitionsEx Retrieve the array of system
Returns a detailed description devices
of logical partitions GlobalVars
GetMemoryInfo Retrieve an array of global
Retrieve information about the variables matching a pattern
system memory usage GUnzip
GetNetPass Uncompress a GZIP binary
Retrieve NETFs password buffer
GetNetStats HDBoot
Retrieve statistics from the Boot the computer on the
network interface specified partition
GetNICs HDCheck

520
Rembo-C functions index
Detect and fix corruptions in a Setup an unicast download
filesystem process
HDClean Interact
Quick-format a partition Bring an interactive evaluator
HideConsole window
Hide the console log window Keyb (LoadKeyMap)
HideProtectedPartitions Change the keyboard mapping
Hide protected partitions by KillRemoteConsole
reducing the disk size Disconnect a remote console
HideWindow KillThread
Hide a window without Kill thread if it is still alive
closing it LinkTree
HWSignature Recursively graft a directory
Get the hardware signature tree to a virtual image
IDEDetect LoadBinaryFile (LoadFile)
Get information for all ATA Load a file in a binary buffer
(IDE) disks LoadCursor
InfoBatchTransfer Load a graphic cursor
Get information about the LoadDir
progress of a transfer process Load a directory
InfoDownload LoadDirMatch
Get information about the Load a directory
progress of a download LoadHexFile
InfoSynchro Load a text file containing an
Get informations about the hex string into a binary buffer
progress of a filesystem LoadMultiUniFile
synchronization Load an multi-valued unicode
InitBatchTransfer file
Setup a multiple file transfer LoadRamDisk
process Load a raw floppy-disk image
InitDownload into a ramdisk
Setup a multicast download LoadTextFile (LoadText)
process Load a text file (codepage
InitRemboCDRom encoded)
Setup cache-to-cdrom cloning LoadUNDI
process Load the PXE UNDI layer
InitRemboFloppy into the memory
Setup cache-to-floppy cloning LoadUnicodeFile
process Load an unicode text file
InitSynchro LoadUTF8File
Setup a filesystem Load an UTF8 text file
synchronization LockKeyboard
InitUDownload Disable the local keyboard

521
Rembo-C functions index
LockMouse MoreRemboClone
Disable the local mouse Continue a cache cloning
LockScreen process
Disable the local monitor MoreSynchro
LogDir Continue a filesystem
Dump the content of a synchronization
directory to the console log MoveTree
Logon Move a file or directory and its
Let the user logon to an content
authentication server NetFile
LogVar Find a host-specific,
Display any kind of variable group-specific or global file
on the console log window NetFullPath
LXBoot (LinuxBoot, Retrieve the global network
LinuxBootEx) path for a given scope
Launch a Linux kernel NewIniFile
MakeDiffFromText Create an empty .ini file
Create a differential image structure
from an edited list of NTAutoLogon
differences Change the auto logon
MakeWindow information on the local NT
Create a window of an optimal computer
size for a given content NTChangeName
MarkShared Changes the name of the local
Count the shared space used NT computer (shortcut)
by an archive NTCleanSignature
MD5Create Force the redetection of the
Initialize a MD5 computation disk geometry by Windows
MD5Finish NTDetect
Terminate a MD5 computation Detect the parameters of a NT
MD5Update system
Update a MD5 computation NTInstallService
MessageBox Install a service on the local
Display a message and wait NT computer
for user feedback NTJoinDomain
MetaCast Join a NT domain
Run a MetaCast synchronized NTMapDrives
transfer (deprecated) Retrieve Windows drive
MoreBatchTransfer mappings
Continue a multiple file NTSetBootTimeout
transfer process Change Windows NT boot
MoreDownload delay
Continue a download process NTSetHostName

522
Rembo-C functions index
Change the TCP/IP name of Open a question dialog
the local NT computer (yes/no dialog)
NTSetNetbiosName ParseIniFile
Change the NETBIOS name Parse an existing .ini file into
of the local NT computer memory
NTSetPartition ParseIniFileDef
Change the NT system Parse an .ini file, or create a
partition to be used new structure
NTSetWinlogonDomain ParseIniString
Change the logon name of the Parse an .ini content stored in
local NT computer a string
OpenArchDevice ParsePartitions
Open an archive of any type Build an array from a list of
OpenArchive partitions
Open a server archive for PatchFile
reading Copy a text file, replacing
OpenDiff expressions on the fly
Open a local archive for PatchIniFile
reading Apply a set of modifications
OpenEval to an .ini file
Open a Rembo-C evaluation PatchSID
dialog Replace all SID occurences in
OpenHTML all registry files
Open an HTML browser PatchSIDReg
window Replace all SID occurences in
OpenMenu a registry file
Open a graphical menu dialog PCIFindDevice
OpenMessage Find a PCI device given its
Open a generic message vendor/device ID
dialog PCIGetBusCount
OpenNotice Get the total number of PCI
Open a notice dialog buses
OpenProgressBar PCIGetSlot
Open a progress bar dialog Get the PCI slot number for a
OpenRegistry given device
Open a Windows NT registry PCIReadByte
edition session Read a byte in PCI registers
OpenShared PCIReadDWord
Manually open the shared files Read a double-word in PCI
repository registers
OpenWindow PCIReadWord
Open a new window Read a word in PCI registers
OpenYesNo PCIWriteByte

523
Rembo-C functions index
Write a byte in PCI registers RemoveCachedFile
PCIWriteDWord Remove a file from the cache
Write a double-word in PCI partition
registers RemoveDir (RmDir)
PCIWriteWord Delete an empty directory
Write a word in PCI registers RemoveFile (FileUnlink)
PortInByte Delete an existing file
Input a byte in a I/O port RemoveTree (DelTree)
PortInWord Recursively destroy a
Input a word in a I/O port directory and its content
PortOutByte RenameDir
Output a byte in a I/O port Change the name of an
PortOutWord existing directory
Output a word in a I/O port RenameFile (FileRename)
PowerOff Change the name of a file
Turn off the computer
RequestDHCPInfo
Printf
Trigger a DHCP negotiation
Format text on the console
and create DHCP variables
window
ResizeWindow
Print (Log)
Change the size of a window
Display text on the console
RestoreDiskImage
window
Restore a disk partition from a
ProbeServer
compressed image
Check if a Rembo server is
RestoreFloppyImage
online
RaiseError Restore a raw floppy image to
Trigger an exception a floppy disk
RDBoot (RamDiskBoot) ScreenSaver
Let the computer boot on the Function called when screen
ramdisk as if it was a floppy saver is activated
RDClean ScreenSaverExit
Format a ramdisk Function called when screen
RDLoad saver is deactivated
Load a compressed image into ScreenShot
a ramdisk Save the content of the display
Reboot in a file
Reboot the computer SendMail
ReleaseDHCP Send a mail to an arbitrary
Tell DHCP server that the email address
address can be reused SetBEER
ReleaseLock Update the protected
Release a named lock on the partitions global parameters
server SetBEEREntry

524
Rembo-C functions index
Update the parameters of a Retrieve the string
given protected partition representation of a numerical
SetBootablePartition size
Define the bootable partition SQLClose
SetIniStruct Close an ODBC session
Update a section in an .ini SQLOpen
structure Open an ODBC session with a
SetIniValue database server
Update a value in an .ini SQLOpenEx
structure Open an ODBC session with
SetIPInfo extra parameters
Activate an IP stack over PXE SQLQuery
UNDI layer Execute a SQL query on an
SetLogicalPartitions open ODBC session
Define logical partitions SQLQuickQuery
SetLogicalPartitionsEx Execute a SQL query
Define logical partitions, with StatShared
details
Sum up the total space used
SetOfflineMode
by marked shared files
Setup the hard-disk to boot
StrChDir
Rembo by default
Compute a normalized path
SetPrimaryPartitions
StrCompare
Define primary partitions
Compare two strings
SetPrimaryPartitionsEx
(case-sensitive)
Define primary partitions,
StrCompareCI
with details
SetProgressBar Compare two strings
(case-insensitive)
Update the progress indicator
in a progress dialog StrCopy
SetProgressInfo Duplicate a fragment of a
Update the informative text in string
a progress dialog StrDelete
SetProtectedPartitions Delete a fragment of a string
Define protected partitions Strf
ShowConsole Format a message in a string
Show the console log window StrFind
ShowWindow Find the occurrence of a string
Show a previously hidden within another
window StrFindCI
SIDToStr Find the occurrence of a
Get the textual representation case-insensitive string within
of a binary SID another
SizeToStr StrFromCP (FromCodepage)

525
Rembo-C functions index
Get a string from a 8-bits Encode a string to a 16-bits
codepage-encoded buffer unicode buffer
StrFromUCS (FromUnicode) StrToUpper
Get a string from a 16-bits Retrieve the uppercase
unicode buffer representation of a string
StrFromUTF8 (FromUTF8) StrToUTF8 (ToUTF8)
Get a string from a Encode a string to a
UTF8-encoded unicode buffer UTF8-encoded unicode buffer
StrGetFileExt StrTrim
Extract the extension from a Remove leading and trailing
filename spaces (and quotes)
StrGetFileName StructKeys
Extract the filename from a Answer the array of keys of a
path structure
StrInsert StructRef
Insert a new fragment in a Retrieve a member of a
string structure
SweepShared
StrLength
Garbage-collect the shared
Answer the character length of
files repository
a string
SymLink
StrMatch
Create a linux symbolic link
Wildcard match (globbing),
Synchronize
case-sensitive
Update a filesystem according
StrMatchCI
to a template image
Wildcard match (globbing),
SynchronizeEx
case-insensitive
Same as Synchronize, but
StrParse return a summary
Split a string into pieces for SynchroStats
given separators Get summary informations
StrPatch about a filesystem
Substitute variable synchronization
expressions in a string SysLog
StrToCP (ToCodepage) Send a message to the server
Encode a string to a 8-bits log
codepage-encoded buffer SysLogF
StrToHTML Send a message to a custom
Encode a string to a HTML server log
7-bits buffer TCPClose
StrToLower Close a TCP connection
Retrieve the lowercase TCPConnect
representation of a string Initiate a TCP connection
StrToUCS (ToUnicode) TCPRead

526
Rembo-C functions index
Read bytes from a TCP Set Windows DNS servers
connection Win2KRegisterBootDevice
TCPWrite adds the PCI IDE controller to
Send bytes to a TCP peer device list
TestIniValue Win2KRegisterHDD
Check for the existence of a Register a hard-drive into
value in an .ini structure Win2k registry
TextDiff Win2KRegisterParts
Create a complete list of Update Windows partition
differences between two layout
configurations Window
TextEdit Retrieve a window widget
Open a text editor window WinEval
Time Evaluate a Rembo-C
Retrieve the current value of expression in a contexted
the internal time counter thread
UnExport WriteOfflineCode
Remove an export declaration Write an offline mode Rembo
UnhideProtectedPartitions boot sector to a device
Unhide protected partitions by WriteRemboProtectedMBR
restoring the disk size Write a MBR that can boot
UnlinkTree into a protected partition
Recursively prune a directory
tree to a virtual image
VarToExpr
Answer a script expression for
a given variable value
VerifyDLA
Verify the consistence of the
shared files repository
ViewDir
Open a directory browser
dialog
Widget
Retrieve a widget object from
its path
WidgetNamed
Retrieve a widget object from
its name
Win2KChangeIPInfo
Set Windows networking
settings manually
Win2KChangeNameServers

527

You might also like