August 12th, 2015

Use PoshUSNJournal Module to Work with Change Journal

Doctor Scripto
Scripter

Summary: Boe Prox shows how to use the PoshUSNJournal module to work with the USN change journal.

Honorary Scripting Guy and Windows PowerShell MVP, Boe Prox, here today, filling in for my good friend, the Scripting Guy. I'm finishing up my three-day stint on the Hey, Scripting Guy! Blog. Be sure to catch up by reading:

Today, I will demo my module called PoshUSNJournal and show you how to use it with the change journal.

I have taken you on the journey of using Windows PowerShell along with PInvoke via reflection to hook into the Windows API to view the change journal and look at the entries to see what is happening on your file system. Although all of this can be done with a little bit of work, it is nicer to have the ability to do it via functions from a module.

This is what PoshUSNJournal aims to do. Not only can you do everything that I have already covered, but this module takes it a little further by letting you wait for incoming entries for a near real-time view of what is happening. You can also configure the journal by removing it and re-creating it with a larger or smaller size!

Are you running Windows PowerShell 5.0? Great! You can install this module with pretty much no effort from the Windows PowerShell Gallery:

Install-Module –Name PoshUSNJournal –Verbose

Image of command output

No worries if you do not have Windows PowerShell 5.0 yet. You can grab the module from my GitHub site: PoshUSNJournal. Place it in your modules folder and you are ready to go!

I’ll start off by showing how quickly we can view the journal by using Get-USNJournal with the DriveLetter parameter:

Get-UsnJournal -DriveLetter C:

Image of command output

Pretty cool, but we want more than that! I can delete this journal by using Remove-USNJournal and create a new one that is a little larger than the 30 MB one that we currently have. Maybe something like 50 MB would be better.

Remove-USNJournal –DriveLetter C: -Verbose

Image of command output

A verification using Get-USNJournal shows that it is, in fact, completely gone from my system.

Of course, I need something here to continue demoing the entries, so I will re-create the journal and set it to be 50 MB in size:

New-UsnJournal -DriveLetter C: -Size 50MB -Allocation 8MB –Verbose

Image of command output

With that done, we can now look at tracking the changes in the file system by using Get-USNJournalEntry.

If you view the Help to see the parameters for this function, you will see that you can actually specify USNReasonMask and basically watch the entries in real-time.

Image of command output

A basic run of Get-USNJournalEntry starts at the beginning of when we created the journal and begins showing all of the changes that have occurred since then.

Image of command output

As you can see, some of this (such as the use of SnagIt) has to do with this very post! If you wanted to view everything, you can definitely do that, but keep in mind that you may be waiting awhile because there could potentially be a lot of data to process. Filtering for a specific file or USNReason code will definitely help out here.

Get-UsnJournalEntry | Where {$_.FileName -match '\.psd1$'}

Image of command output

In this case, I wanted to see if I had any .psd1 files that had been updated since I created the journal. It turns out that I did, and I can see that it was actually deleted.

The last thing I will show is monitoring the journal by using the –Tail and –Wait parameters:

Get-UsnJournalEntry -DriveLetter C: -Tail –Wait

Image of command output

Take note of the New Text Document.txt and TestFileToDelete.txt files. These are the same files, but you can see how the first file was created (using right-click on the Desktop and Create new text file). This shows how the file was created prior to me renaming it.

You can see the file is then sent to the recycle bin via its new name: $I27RNAF.txt and its subsequent return from the recycle bin (under the USN_REASON_RENAME_OLD_NAME and USN_REASON_RENAME_NEW_NAME masks). The hard deletion is presented under the USN_REASON_FILE_DELETE mask. You can also see that other changes were made on the file system while I was testing against the text file.

With that, we are done exploring the USN change journal by using Windows PowerShell. We explored two methods—we took a dive using PInvoke with reflection and we used my module, PoshUSNJournal. (This module is available on GitHub and it is always available for pull requests to make it better!)

We invite you to follow the Scripting Guys on Twitter and Facebook. If you have any questions, send email to the Scripting Guy at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. Until then, see ya!

Boe Prox, Windows PowerShell MVP and Honorary Scripting Guy

Author

The "Scripting Guys" is a historical title passed from scripter to scripter. The current revision has morphed into our good friend Doctor Scripto who has been with us since the very beginning.

0 comments

Discussion are closed.