Tachyon PowerShell Toolkit management cmdlet reference
List of Tachyon PowerShell Toolkit cmdlets used for Tachyon management.
These cmdlets allow you to perform a variety of tasks in Tachyon. Some of them are discussed in the parent page, in relation to dynamic scripting and cmdlet creation. However, there are other cmdlets which support interaction with Tachyon. These are discussed on this page.
Related topics
The Tachyon PowerShell Integration Toolkit provides additional functionality, which is explained in more detail at the links below.
Scope and filter expressions
Scope expressions allow you to flexibly target devices based on criteria such as device FQDN, operating system version, management group etc.
Scope expressions also support device tags. Device tags are a Tachyon feature which allows you to easily 'label' devices with arbitrary property sets. For example, using device tags you can label all database servers and then target only that device set in an instruction by specifying the tag and value.
Filter expressions allow you to specify the data you actually want to be returned from devices. This allows you to efficiently return just the information you require, for example, all devices with two populated memory slots.
For more information on scope and filter expressions, see Using scope and filter expressions with the Tachyon PowerShell Toolkit.
Staged rollouts
Staged rollouts allow you to target tranches of devices with an instruction and automatically keep track of the devices that have received it, for each deployment tranche.
For more information on staged rollouts, see Staged rollouts using the Tachyon PowerShell Toolkit.
OSQuery integration
OSQuery is an open source initiative developed by Facebook's engineers. Like Tachyon, it provides a set of device-level queries expressed via SQLite queries. The functionality available through OSQuery extends that available natively via the Tachyon agent. The PowerShell Integration Toolkit lets you invoke any OSQuery query without requiring additional installed software on devices.
For more information on OSQuery integration, see OSQuery integration.
WMI integration
WMI integration allows you to directly execute a WMI query against a targeted set of devices. For more information, please refer to WMI Integration.
Dynamic cmdlet creation from Tachyon instructions
The PowerShell Integration Toolkit allows you to easily create new PowerShell cmdlets from existing Tachyon instructions. The page here discusses a scenario where a useful Tachyon instruction is turned into a cmdlet for reuse, Creating your own cmdlet from a Tachyon instruction.
Workflow management cmdlets
Workflow management cmdlets allow you to manage the workflow associated with Tachyon instructions which have been defined as actions, rather than questions.
Workflow tokens
The normal workflow process in Tachyon is as follows:-
The action invoker requests that a specific action be invoked. If using PowerShell, this would be via any of the cmdlets that ultimately invokes instructions via the invoke-instruction cmdlet.
Tachyon emails the action invoker with a one-time token. The token is valid for ten minutes.
Within the ten minute timeframe, the action invoker binds the token to the instruction Id using the Set-TachyonInstructionAuthToken cmdlet below. This verifies the authenticity of the invoker.
The action is now placed in a 'pending approval' state. The action approver then uses the Approve-Instruction or Deny-Instruction cmdlets below to accept or reject the action. There is no timeframe within which they need to do this.
If the action was approved, it will now execute. The invoke-tachyoninstruction cmdlet automatically loops, waiting for the instruction to be approved.
If the action was rejected, it transitions to the rejected state. The invoke-instruction cmdlet will throw an error at this point, indicating that the instruction was rejected.
If the action invoker and the action approver are the same person, they can use the Approve-TachyonInstruction or Deny-TachyonInstruction cmdlets to approve or reject an action in a single operation. They do this by also supplying the optional authentication token to these cmdlets.
Note
Normally an invoked action will cause the invoke-instruction cmdlet to wait until the instruction is either approved and then the results become available, or until the instruction is rejected or enters an error state, at which point the cmdlet raises an error.
In some cases the action invoker might want the invoke instruction cmdlet to return when the instruction is initially submitted. They can do this by specifying the -NoWait parameter when invoking the instruction. In this scenario, the invoke-instruction cmdlet returns immediately. The instruction invoker can subsequently use the get-tachyoninstructionresult cmdlet to retrieve the instruction results at a future point when the instruction was approved and has executed. Note that results will only be available for the duration of the results time-to-live (TTL) value associated with the instruction when it was initially submitted.
Approve-TachyonInstruction -Id <id> | -ScheduleId <scheduleId> [-Token <token>] [-Comment <comment>]
Approves the instruction or scheduled task creation request, given by the specified Id, using the authentication token provided.
If the token is not provided, it is assumed that the token was already set using the Set-TachyonInstructionAuthToken cmdlet. This is most probably because the approver is not the same person as the instruction invoker.
You cannot re-use an authentication token. Providing the token again in this cmdlet when it has already been supplied via Set-TachyonInstructionAuthToken will raise an error. Providing the token when it was issued to another user will also raise an error.
The optional comment will be used as the reason for approving the instruction. If not supplied, a default comment 'This instruction was approved by Tachyon PowerShell Integration' is used.
Deny-TachyonInstruction -Id <id> | -ScheduleId <scheduleId> [-Token <token>] [-Comment <comment>]
Rejects the instruction or scheduled task creation reques given by the specified Id, using the authentication token provided.
If the token is not provided, it is assumed that the token was already set using the Set-TachyonInstructionAuthToken cmdlet. This is most probably because the approver is not the same person as the instruction invoker.
You cannot re-use an authentication token. Providing the token again in this cmdlet when it has already been supplied via Set-TachyonInstructionAuthToken will raise an error. Providing the token when it was issued to another user will also raise an error.
The optional comment will be used as the reason for rejecting the instruction. If not supplied, a default comment 'This instruction was rejected by Tachyon PowerShell Integration' is used.
Note
For both of the above cmdlets, if the token is omitted but the instruction invoker did not already bind it to the instruction Id, then an error is thrown. However, the error returned from Tachyon is somewhat misleading as it states that the approval request has already been actioned by the user '.' This appears to be a defect currently in the Tachyon response.
Set-TachyonInstructionAuthToken -Id <id>|-ScheduleId <ScheduleId> -Token <token>
Sets the authentication token for the instruction or scheduled task creation operation. This cmdlet is useful in scenarios where the approver is not the same individual as the instruction invoker. In that situation, the instruction invoker will receive the authentication token and will then use this cmdlet to bind it to the instruction they invoked.
The instruction approver will then use the Approve-TachyonInstruction or Deny-TachyonInstruction cmdlet without the token, to approve or reject the instruction accordingly.
Note
The instruction invoker must bind the token to the instruction within ten minutes of invoking the instruction, otherwise it will automatically transition to 'rejected'.
The token is only valid for the account associated with the instruction invoker. If it is supplied in the context of a different account, an error will be raised.
Instruction invocation and the -NoWait parameter
An action invoked from a PowerShell session will block that session until the action is approved. The instruction invoker must therefore use a second PowerShell session to bind the authentication token and optionally self-approve (where applicable) their action.
The instruction invoker may prefer that the action be queued and control returned immediately to their primary PowerShell session. In that scenario, the -NoWait parameter to the invoke-instruction cmdlet allows the instruction invoker to queue the instruction and immediately regain control within a single PowerShell session.
They must still retrieve the authentication token and bind it to the instruction and/or self-approve before the action executes, but they can do so from within a single PowerShell session if preferred.
Instruction results can then be subsequently retrieved using the get-Tachyoninstructionresults cmdlet.
A workflow scenario in more detail
Using device tags with the Tachyon PowerShell Toolkit has a detailed workflow scenario using the above cmdlets.