en-us/about_PSRemoteOperations.help.txt

TOPIC
    about_PSRemoteOperations
 
SHORT DESCRIPTION
    This topic file explains the concepts and commands around a process called
    PSRemoteOperations. The premise is that a computer is monitoring a given
    folder looking for a file with a name that matches the computer name. When
    found, the file can be parsed and the designated scriptblock or script file
    executed. Upon completion the original file is deleted and an archived copy
    is created which contains metadata about the operation and its result.
 
LONG DESCRIPTION
    This module is predicated on the idea that you might have a computer or
    server that utilizes some type of cloud service, such as DropBox or
    OneDrive. Or the remote computer has access to a common folder such as a UNC
    path. The concept is that you create a PSRemoteOperations file in "your"
    copy of the folder. The folder is "replicated" to the remote computer.
    The remote computer has some sort of "watcher" that is monitoring the
    folder. When it detects a matching file, it is parsed and executed. The end
    result is that you can invoke a command on a remote machine without relying
    on PowerShell Remoting.
 
    GLOBAL VARIABLES
    It is strongly recommended that you define two global variables in your
    PowerShell profile script. The commands in this module are designed to use
    the variables as default.
 
    $PSRemoteOpPath will be the path where the PSRemoteOperation files will be created.
 
    $PSRemoteOpArchive will be the path where the archive files will be created.
    Typically, this will be a sub-folder of $PSRemoteOpPath.
 
    PS C:\> mkdir c:\users\jeff\dropbox\ops\archive
    PS C:\> $PSRemoteOpPath = "c:\users\jeff\dropbox\ops\"
    PS C:\> $PSRemoteOpArchive = "c:\users\jeff\dropbox\ops\archive"
 
    If you use the global variables, the Computername parameter will
    autocomplete for Get-PSRemoteOperationResult and New-PSRemoteOperation
    based on files in the archive folder.
 
EXAMPLES
    With these default variables, here's how you might use the commands in this
    module. First, you need to create an operation file.
 
    PS C:\> New-PSRemoteOperation -Computername SRV1 -Scriptblock {restart-service spooler -force}
 
    This will create a file using the naming convention computername_guid.psd1.
    It is assumed that the destination path, $PSRemoteOpPath, is being replicated
    in some way to the remote computer, SRV1. You can also create multiple remote
    operations file to run the same script or scriptblock.
 
    PS C:\> $computers = Get-Content computers.txt
    PS C:\> New-PSRemoteOperation -Computername $computers -Scriptblock {
        if (-Not (Test-Path C:\Work)) {
            mkdir c:\work
        }
        Copy-Item C:\Data\foo.dat -destination C:\work
    }
 
    This will create multiple psd1 files with the same scriptblock but for each
    computer in the $Computers variable.
    The remote computer needs some means of monitoring the target folder and
    invoking the file when detected. You can use whatever means you want. You
    may want to setup a FileWatcher or WMI Event subscription. You may have 3rd
    party products you can use. However you monitor the folder, once you've
    identified a matching file, use Invoke-PSRemoteOperation to execute it.
 
    PS C:\> Invoke-PSRemoteOperation $file -archivepath c:\archive
 
    Once the operation is complete, the original file is deleted and an archive
    version is created in the archive path location. If you placed your archive
    as a sub-directory, the results will "replicate" back to you.
    On your computer, you can use Get-PSRemoteOperationResult to get the results
    from one or more computers or operations.
 
    PS C:\> Get-PSRemoteOperationResult -Computername SRV1 -Newest 1
 
            Computername : SRV1
            Date : 10/02/2018 21:29:35 UTC
            Scriptblock : restart-service spooler -force
            Filepath :
            ArgumentList :
            Completed : True
            Error :
 
    In this example, the command is getting new last result for computer SRV1.
    It is up to you to manually manage the archive folder, deleting files as you
    need to.
    The module includes a command to setup a default "watcher" using a
    PowerShell scheduled job.
 
    PS C:\> Register-PSRemoteOperationWatcher
 
    You will be prompted for your user credentials. This will create a scheduled
    job called RemoteOpWatcher that will check every 5 minutes for matching
    files in $PSRemoteOpPath and use $PSRemoteOpArchive for the archive
    path. Use the scheduled job cmdlets to modify or un-register. Note that the
    job won't start for 2 minutes upon initial setup. But thereafter it will run
    indefinitely and survive reboots.
 
SECURITY
    It is assumed that you are taking the necessary precautions to protect and
    secure the locations for the PSREmoteOperations files. Presumably, if you
    are using a cloud-based service like DropBox your files already have one
    layer of protection. But if you are using something internal, such as a file
    share, you will need to carefully watch access control.
 
    Another option is to create the PSRemoteOperations files as protected CMS
    messages as you would with the Protect-CMSMessage cmdlet.
 
    New-PSRemoteOperation has a To parameter which takes a CMSMessageRecipient
    as a value. All other commands will seamlessly detect if you are using a CMS
    Message or not and automatically handle decryption.
 
    This process will require the same documentation encryption certificate on
    the system where you are creating the files as well as the remote computer.
    In order to properly decrypt the message, the computer will need the private
    keys. For the sake of simplicity, install the certificate with private keys
    on every computer you intend to run remote operations.
 
    CMS Messages are not supported on non-Windows platforms. Any CMS-related
    parameters in this module are dynamic and ignored on non-Windows platforms.
 
PowerShell Core
    The long-term goal is to ensure that this module will work cross-platform
    and in PowerShell Core. Support for CMS messages is limited to Windows
    platforms through the use of dynamic parameters.
 
    Register-PSRemoteOperationWatcher requires a Windows platform but should
    work under PowerShell Core. For non-Windows systems, you will have to come
    up with your own tooling for monitoring and execution using
    Invoke-PSRemoteOperation.
 
NOTE
    This module is intended to run local commands on a remote machine. Passing
    credentials or running commands to remote machines where authentication
    might be required is still under development and testing.
 
    **TEST AND VERIFY ALL COMMANDS IN THS MODULE IN A NON-PRODUCTION ENVIRONMENT
    ESPECIALLY IF USING DOCUMENT ENCRYPTION.**
 
TROUBLESHOOTING NOTE
    Please report any issues, bugs, comments or feature requests in the module's
    GitHub repository at:
 
    https://github.com/jdhitsolutions/PSRemoteOperations/issues
 
SEE ALSO
    Protect-CMSMessage
 
KEYWORDS
    RemoteOperation