Ilja Godau Releases Tool to Automatically Document your Citrix PS4 Environments

Written on Jul 26 2005 Filed under: Citrix, Technical Articles 21,162 views, 30 comments

by Ilja Godau

Being a Citrix consultant in Denmark working for TopNordic A/S, I not only design and implement Citrix Presentation Server solutions, but I often have to take a look at implementations done by other consultants. Many times I’ve wanted to pull out the complete documentation of an installation as seen in the Management Console for Presentation Server. As far as I know there no tool for this. Yes, scripts exist for a few options out there, but there’s no complete solution. Manually documenting all the published applications and connections policies is weary work, especially since Citrix is putting more and more stuff into these.

The Citrix PS4 Documentor (or “documenter” for you Americans) is my shot at such a tool that can hopefully avoid pages of screen dumps in the future.

Okay, so what do I do?

The Documentor is easy to use. Just make sure you have the 'Citrix PS4 Documentor.exe' and the 'mfcom.dll' file in the same directory on your PS4 server. (It is important to run it from a PS 4 server itself.) Run 'Citrix PS4 Documentor.exe' and sit back! The program will create HTML files for every section in the same folder that the 'Citrix PS4 Documentor.exe' is executed from.

When documenting your published applications, a folder called 'PS4DocumentorIcons' will be created in your %systemdrive% folder. This folder holds ICO files which are used by the 'Applications Settings.html' file. If you want to transfer this HTML file to another location, remember to also copy the 'PS4DocumentorIcons' folder if you want to have the icon image retained. You may have to edit the HTML file to reflect the correct location of the icon files.

Finally, yes, you have to be logged in with a full Citrix Administrator account. No rights means no documentation! The same goes for the section about the icon folder. No rights for creating a folder on the system-drive means no documenting your published applications.

And that’s about it.

Prerequisites

The Citrix PS4 Documentor needs the Microsoft .NET Framework to be installed. Version 1.1 is preferred.

As its name implies, the Citrix PS4 Documentor only works on Presentation Server 4 servers. Non-PS4 servers are allowed in your farm, but this is not what the software was designed for so it might not work exactly right.

What if I don’t like the layout of the HTML files?

Bummer... <SMILE>

Just open the HTML file, press CTRL-A, press CTRL-C, and paste it into your favorite text or HTML editing tool and change it.

Known Issues

This tool uses MFCOM to extract the information from the Citrix farm, although some settings cannot be accessed via MFCOM, including Resource Manager and Installation Manager settings.

Either due to bugs in the Citrix SDK or my lack of programming experience, some settings generate errors and cannot be documented. (See the readme file for details.)

A Note from Author

I am no great programmer and knocked this together with a simple software editor, so if you find any bugs then please report them to me at ilja@godau.dk.

I am not responsible if you use this program and lock up half your company’s machines or domain. You use this program at your own risk!

I have tested it here on my local domain with Windows Server 2003 and Citrix Presentation Server 4 Enterprise Edition with no problems and it should work on Windows 2000 Server and Citrix Presentation Server 4 Standard and Advanced Edition, but no guarantees are given. Also it does NOT write to the datastore—it just queries it through MFCOM.

Any feedback good or bad welcome to ilja@godau.dk or feel free to share your comments below.

Comments

Brian Madden wrote You know what would be cool?

on 07-26-2005 10:00 AM

I think it would be cool if we could make this thing generate it's output in an XML format. We could specify an XML document type for server farms. Then it would be easy to transform the content into a configuration database, HTML, text reports, etc, etc.

Of course since I'm not a programmer, I don't know how hard this would be. Actually it would probably be easier than making HTML. Do you want me to get started on an XML document spec?

Brian

Mark Schill wrote XML Reference

on 07-26-2005 10:40 AM

I started an open source project at http://sourceforge.net/projects/cmfie to dump the information to xml. I haven't had much time to play with it lately. Feel free to take a look at my xml definitions and stylesheets if you would like.

Tom Howarth wrote PS4 Documentor

on 07-26-2005 3:48 PM

this is another fine example of why I love this community.

is there any posibility of making it able to document older versions, it would save a hell of a lot of time in Migrations ;-))

Shawn Bass wrote RE: PS4 Documentor

on 07-26-2005 4:01 PM

ORIGINAL: tstsh

this is another fine example of why I love this community.

is there any posibility of making it able to document older versions, it would save a hell of a lot of time in Migrations ;-))


Mark's utility up on SourceForge should work with earlier versions.

Ilja Godau wrote Re: PS4 Documentor

on 07-26-2005 4:18 PM

I actually started doing this for PS3 and got part of the way, but never finished it completely...and then PS4 came out and I had to change focus.

I might still have som VB-scripts laying around somewhere for PS3. I will mail them to Brian for posting if I find them...

And you are not the first mentioning this for migration projects...so as time permits I will try out the program on PS3 and maybe even MFXP and see where it may fail and build some checks in...but no guarantees and time frame will be given out just yet.

Ilja Godau wrote Re: You know what would be cool?

on 07-26-2005 4:21 PM

Nice idea...as I have mentioned I'm not a programmer and have actually not worked with XML-files, but how hard can it be? I guess it's not rocket-science.

Give it a shot and in the meantime I look into XML-files technology and Marks definitions.

Ilja Godau wrote Re: XML Reference

on 07-26-2005 4:24 PM

Hmmm...looks good. I guess I have to look into C# and XML soon <SMILE>.

And one tip for your program...it will fail if you have a server in your farm which is not online...ran into the same problem, so my test farm is with at least one server offline. Just for testing purposes and to catch the exception.

Guest wrote Older Farm Support

on 07-26-2005 6:54 PM

Glad that there is a new tool out. I was actually following progress with the code at http://sourceforge.net/projects/cmfie. These application can be of significant help to admins + they are free.

For those that need old farm info my "iFarm" tool might help too. Although it was not updated since June 2004 it should be operational ;)

http://www.tekworkshop.com/welcome/modules.php?op=modload&name=News&file=article&sid=33

ALEX

brian lilley wrote good stuff igodau!

on 08-19-2005 12:55 PM

This is also a tool I had been working on for PS3 farms and gave up. My plan was to provide a disaster recovery tool. That is, firstly the tool scans the farm for all known objects and lays them out in XML format. And when the datastore goes ***-up... and perhaps a backup is not available. you run this tool and it rebuilds your farm for you.. bish bosh bash.

Guest wrote great tool

on 08-19-2005 5:17 PM

I wish there was a tool like that that would've worked on MPS3.0.

Guest wrote Great Subject!

on 08-27-2005 10:17 AM

There is a third party add on called Harvester which allows you to save published app settings to an HTML file and you can then use this to build or re-build servers.

It also allows you to make farm wide changes.

www.centralis.co.uk/harvester

Hope this is useful!
Citrix Administrator in the UK

Guest wrote Most current version is where??

on 09-15-2005 9:05 AM

Is the posted zip file the most current version??
Thank you,
Tom

Guest wrote RE: Re: PS4 Documentor

on 01-13-2006 9:36 AM

First off - thanks for the utility, it's great.  I installed some Windows Update and now it errors out during the "Applications" portion.  The other areas work with no problem.  Due to our company policy I can't uninstall any of the security updates but I was wondering if you had any ideas to re-enable this.  We are running Windows 2003 with no SP and PS 4.0.

The error dialog box says Microsoft .Net in the title and the following text:
An unhandled exception has occurred in your application.  If you click Continue, the application will ignore this error and attempt to continue.  If you click Quit, the applicatino will be shut down immediately.

There is a details button which gives a bunch of information but none of it makes sense to me, it's lengthy so I didn't want to post it unless someone thinks it would help.

Guest wrote Excellent tool

on 02-27-2006 5:08 AM

wow.. It really helped... thx to I Godau !
 
Prolböl

Guest wrote Excellent tool

on 02-27-2006 5:10 AM

ups.. my signature didn't work ...
 
Prolboell ...

Guest wrote RE: Excellent tool

on 03-02-2006 9:16 AM

Are there known issues with .net 2.0?

Guest wrote RE: PS4 Documentor

on 04-04-2006 7:24 AM

Hello... great Tool! Im also having trouble with that error message poping up... This happens when pushing the Policies button. Anybody have clue as to why this "crashes"????????

Shawn Bass wrote RE: PS4 Documentor

on 04-04-2006 11:27 AM

ORIGINAL: Guest

Hello... great Tool! Im also having trouble with that error message poping up... This happens when pushing the Policies button. Anybody have clue as to why this "crashes"????????


Did you install the .NET Framework 2.0?  If so, that's probably why you're getting the error.

Shawn

Nat Foley wrote RE: PS4 Documentor

on 03-12-2007 10:12 AM

did anyone get to the bottom of the .net error mentioned above?
I'm seeing the same thing using .Net 1.1 and PS4 Documentor v1.3.

Guest wrote Program Excenptoin

on 07-03-2007 5:24 AM

Does someone have the source code?

Guest wrote How to Use

on 07-19-2007 10:37 AM

Do you have to run this on each citrix server in the farm or is there a specific server it needs to run from such as the data collector?

Guest wrote Will it work with 4.5

on 07-19-2007 12:04 PM

Will it?

Guest wrote The server threw an exception

on 08-10-2007 3:06 PM

I get this error when I try to document my published apps.  Anyone know what it means?

 

See the end of this message for details on invoking
just-in-time (JIT) debugging instead of this dialog box.

************** Exception Text **************
System.Runtime.InteropServices.COMException (0x80010105): The server threw an exception.
   at Microsoft.VisualBasic.CompilerServices.LateBinding.LateGet(Object o, Type objType, String name, Object[] args, String[] paramnames, Boolean[] CopyBack)
   at PS4_Dokumentation.MainForm.Applications_Click(Object sender, EventArgs e)
   at System.Windows.Forms.Control.OnClick(EventArgs e)
   at System.Windows.Forms.Button.OnClick(EventArgs e)
   at System.Windows.Forms.Button.OnMouseUp(MouseEventArgs mevent)
   at System.Windows.Forms.Control.WmMouseUp(Message& m, MouseButtons button, Int32 clicks)
   at System.Windows.Forms.Control.Wnd