Supporting administrators using Application Streaming, one of the items that comes up from time to time is RadeRunSwitches.  They can be a good tool for running applications and even more important, for debugging the operation of a streamed application. 

This post describes the undocumented switches...

The Application Streaming client exists as part of Presentation Server 4.5 and later versions.  It works in conjunction with the PNAgent Win32 ICA Client as well as the Web Interface clients that run on the Windows platforms.  This is true both on user machine "client side" as well as server hosted, stream to server.

The icon placement and decision to launch an application happen in PNAgent and/or the Web Interface. These two components eventually toss the execution over the wall to the Streaming Client who does the actual work of running the Streamed application.  In the diagram below, the Streaming Client components are in green and the publishing components are in blue.

.

The executable that receives the launch request is RadeRun.exe.    RadeRun's mission is to carry out the launch request, via a single set of code that may be called from multiple sources.  Classic computer science stuff here; implement the launch logic once and you can be confident that if it works for one, it will work for the other and you get a single point of maintenance.    The "true" flow between the various components is a bit more involved than the above, but in principle, this is how it works.

Back to the beginning

In the earliest days of Application Streaming development, the PNAgent and Web Interface teams were not yet engaged.   All execution of applications started with RadeRun.   Early programming, testing and proof of concept were all done using RadeRun.exe as a command line utility to trigger the execution of streamed applications.  Some of this legacy remains even though PNAgent and the Web Interface are now quite capable of communicating with the streaming service without an intermediary. 

Isolation layers

In a minute, I will go through each of the switches to RadeRun - but first it helps to have an understanding of the isolation layers used in Application Streaming.

The application views the machine from above looking down.  The higher levels are like panes of glass laid on top of a business desk. The desk represents the true disk and true registry of the execution machine.  The application is above looking down and the layers of isolation glass "mask" the application's view of the true machine.    The layer of glass in the middle is read only at application execution, but was writable during profiling.  This layer represents the execution image for the application and is sometimes called the "InstallRoot" in documents describing Application Streaming.

The top layer is a per-user image and is writable at application runtime.  The application view of the true machine is masked from top to bottom, first by the per-user space and then by the installation image.   The application runs from above, looking down through the panes of isolation glass and since the middle layer represents what was written during profiling and since the top layer of glass starts clear, the initial application view of the machine is what existed at profiling.  The application believes it is installed - when it is not.  Each user gets their own top layer of glass and it is this layer that is writable at runtime.  This way, if an application writes to isolated spaces at runtime, that write is held in the per-user space.  Put it all together and applications not written for clean execution on a multi-user system can run without conflict.  More, the per-user pane of glass stays with the user's profile and can follow them from session to session.

The above applies to both disk and registry.  It also applies to COM objects and the systems named addressable items like PIPES and named semaphores.  

Lies, damn lies and statisticians:

The execution image (middle layer) is not really there.  Instead the isolation system lies and tells the application that the installation image is present on the machine and this reduces the amount of stuff that has to be brought down to the execution machine to run the application.  Many applications, particularly big ones, only reference a small portion of the stuff they install.  More classic computer science stuff says that if you can put off copying that data to the execution machine long enough, maybe you can avoid it permanently. 

Now - you'll notice a few important things.  Files that need to be there aren't and the isolation system has to do stuff to make them look like they are there and eventually, when actually needed, it has to make them really there, pausing and resuming the executing application while filling the missing content.  Worse, complicated things like Short File Names exist on the profiling machine and these names need to be maintained all the way to execution machine even if the TRUE short file name on the execution machine doesn't match the one that was used during profiling.  The application must see the SAME name no matter what and there is no reliable system API to make this happen.  The list goes on - bottom line is that there's lots of work to make these layers work and this means that there is lots of testing needed to prove that it works.

Proving it works

Once the execution cache becomes "full", very few runtime cache fills occur.  If you're in the business of testing the cache fill logic, this is no good.   Consider "stress" test in one of the Citrix labs.  The test is 100s of servers, 30 users on each server with all the users all running a variety of streamed applications.   The test then runs for about 24 hours and if anything ever fails, the test stops and your phone rings.  "They don't call it the stress lab for nothing!".

How can testers get the cache empty when the cache is being filled?

Answer: Backdoor logic to tell the streaming service to purge the cache before the application starts. Variations of this exist to control flushing all of the layers in the isolation system and to control "when" the flushing occurs.    This backdoor logic is controlled via command line arguments to RadeRun.exe.  There's one trick.  RadeRun.exe is not directly used for testers or users to launch applications. Instead, the applications launch via the web interface or PNAgent.   

Quandary:  If you don't "run" RadeRun directly, then how do you give it command line arguments? 

Answer: Registry key

HKLM\Software\Citrix\Rade\RadeRunSwitches (Reg_SZ)

RadeRun still accepts directly provided command line parameters, but it also checks a registry key for additional parameters.  With this, you can give command line arguments to the Streaming Client launcher even though you're not directly using RadeRun to trigger the execution of an application.

Evertything so far has discussed "why" RadeRunSwitches exist.  We can finally get to what they are. RadeRun.exe command line parameters

Specify using registry: HKLM\Software\Citrix\Rade\RadeRunSwitches (Reg_SZ)

c    clear execution cache before app opens

C   clear execution cache and per-user cache before app opens

d    clear execution cache after app closes

D    clear execution cache and per-user cache after app closes

e    Pre-fill everything into the execution cache

x    launch cmd.exe inside of isolation when launch the streamed application

Example contents: "-C -x"

*Are they documented or undocumented?

Now that I've written this, they are documented.  That said, in theory, with the exception of -x, they aren't needed much or more precisely - shouldn't be needed much.   The sections below will give more color to each of the switches;  what they do and where they should be used.

-c

Useful for the Citrix test groups to cause high-exercise for the isolation systems cache fill logic. Not really useful for customers as it results in all application launches being a first time launch, and first time launches are "slow" compared to a second time launch.  

-C

Same as the lowercase version, but clears BOTH the execution cache and the per-user cache.  People still tend to code this as -c -C when running the switches.  It actually makes more sense to me that -c should control the execution cache and -C control the per-user cache, but that isn't how it is.

-d

Useful for the Citrix test groups to cause high-exercise for the isolation systems cache fill logic.  In some cases, this one is useful for customers. If you have "secret" stuff that is part of your execution image and you want it "gone" after the application terminates, then -d can be an answer.  I'll add that the execution cache is DACL protected and users who are not running the application "right now" can't see it.  That said, some folks have good reason to be paranoid and this switch tells the streaming client to purge the cache when application terminates.  Notice that -d, like -c will cause the next launch to be "a first time launch" every time, and first time launches are "slow" compared to a second time launch.  

I normally recommend avoiding -c and -d and instead using a post-exit script to delete the just the smallest amount of secret stuff.  This way, the application launches are not first time penalized and the secret stuff is gone after execution.   The post exit script deletes the secret stuff and the next launch brings it back with a runtime cache fill.  Presumably, the secret stuff is small compared to the whole app.

-C

Same as the lowercase version, but clears BOTH the execution cache and the per-user cache.

-e

No longer needed.   In my first rounds of "documenting" RadeRunSwitches, I didn't even put this one on the list.  -e was created during development to allow the isolation system to run applications even before the cache fill logic was coded.   Today, it is sometimes used to diagnose a suspected cache fill error - or more precisely, a suspected "escape" from isolation.  If an application "works" with -e and doesn't work without it, then it implies that something isn't being isolated right and needs to be diagnosed. I do not recommend the use of -e in production systems but it can be useful in debugging applications.

UPDATE (04-Apr-08): I have been told of a worthy use of -e.   If an application is run with -e enabled as a part of a maintenance activity, then the entire cache can be filled; and then -e turned off.  This as a means of ensuring fastest possible launch time for users even if no user has ever logged on that client machine or server.  Application Streaming still does all the central publishing and applicaiton isolation stuff, but the streaming part not really used.  Interestly in this scenario, RadeRun.exe can be used directly.  Its fun to see how stuff gets used.

-x

This is my absolute favorite of the bunch and the real reason for documenting the switches. 

Notice that -x has nothing to do with cache management.   When profiling and testing profiled applications, it is often useful to have a command prompt or other utility running next to the streamed application and "seeing what the app sees".   Adding CMD.exe to the application profile and then publishing it is one way to get this accomplished.  This was common during the early days of Application Streaming development - until the developers got tired of repeatedly publishing a command prompt with every created profile.   Adding a switch to the RadeRunSwitches allows very quick addition of an in-sandbox command prompt for any streamed application.  This simplifies diagnosis of failing systems because you don't have to ask the person that created the profile to go back and change it to add debugging information.  Regedit to add the switch, launch the application and "poof!" a command prompt inside the same isolation environment as the launched application.

TIP: If you're debugging more than one application at a time, it is useful to use the "title" command to label your command prompts.

If you run regedit, from the command prompt, then regedit will see the view of the system that the isolated application sees, handy.  Do know though that you need to not have regedit already running for this to work because a second instance of regedit kicks the execution over to the first and then terminates.

Killing sandboxes: If you're running applications and particularly if you're writing scripts for your profile, you need to know that the sandbox does not terminate until all of the isolated applications in that sandbox terminate.  The started command prompt is "part of the sandbox" so it too must close for the sandbox to end. 

Wrap up

I hope this information is useful.  If you have comments or ideas for other switches, post here or let me know.

Joe  Nord
Product Architect Application Streaming, Citrix Systems, Fort Lauderdale, FL