Ansible
PS DSC
Downloads:
69
Downloads of v 2411.9.17:
21
Last Update:
17 Nov 2024
Package Maintainer(s):
Software Author(s):
- JJ Fullmer
- FOG Project
Tags:
psmodule fog fogapi imaging provisioning fogproject
FogApi Powershell Module
- 1
- 2
- 3
2411.9.17 | Updated: 17 Nov 2024
Downloads:
69
Downloads of v 2411.9.17:
21
Maintainer(s):
Software Author(s):
- JJ Fullmer
- FOG Project
FogApi Powershell Module 2411.9.17
Legal Disclaimer: Neither this package nor Chocolatey Software, Inc. are affiliated with or endorsed by JJ Fullmer, FOG Project. The inclusion of JJ Fullmer, FOG Project trademark(s), if any, upon this webpage is solely to identify JJ Fullmer, FOG Project goods or services and not for commercial purposes.
- 1
- 2
- 3
All Checks are Passing
3 Passing Tests
Deployment Method: Individual Install, Upgrade, & Uninstall
To install FogApi Powershell Module, run the following command from the command line or from PowerShell:
To upgrade FogApi Powershell Module, run the following command from the command line or from PowerShell:
To uninstall FogApi Powershell Module, run the following command from the command line or from PowerShell:
Deployment Method:
This applies to both open source and commercial editions of Chocolatey.
1. Enter Your Internal Repository Url
(this should look similar to https://community.chocolatey.org/api/v2/)
2. Setup Your Environment
1. Ensure you are set for organizational deployment
Please see the organizational deployment guide
2. Get the package into your environment
Option 1: Cached Package (Unreliable, Requires Internet - Same As Community)-
Open Source or Commercial:
- Proxy Repository - Create a proxy nuget repository on Nexus, Artifactory Pro, or a proxy Chocolatey repository on ProGet. Point your upstream to https://community.chocolatey.org/api/v2/. Packages cache on first access automatically. Make sure your choco clients are using your proxy repository as a source and NOT the default community repository. See source command for more information.
- You can also just download the package and push it to a repository Download
-
Open Source
-
Download the package:
Download - Follow manual internalization instructions
-
-
Package Internalizer (C4B)
-
Run: (additional options)
choco download fogapi --internalize --source=https://community.chocolatey.org/api/v2/ -
For package and dependencies run:
choco push --source="'INTERNAL REPO URL'" - Automate package internalization
-
Run: (additional options)
3. Copy Your Script
choco upgrade fogapi -y --source="'INTERNAL REPO URL'" [other options]See options you can pass to upgrade.
See best practices for scripting.
Add this to a PowerShell script or use a Batch script with tools and in places where you are calling directly to Chocolatey. If you are integrating, keep in mind enhanced exit codes.
If you do use a PowerShell script, use the following to ensure bad exit codes are shown as failures:
choco upgrade fogapi -y --source="'INTERNAL REPO URL'"
$exitCode = $LASTEXITCODE
Write-Verbose "Exit code was $exitCode"
$validExitCodes = @(0, 1605, 1614, 1641, 3010)
if ($validExitCodes -contains $exitCode) {
Exit 0
}
Exit $exitCode
- name: Install fogapi
win_chocolatey:
name: fogapi
version: '2411.9.17'
source: INTERNAL REPO URL
state: present
See docs at https://docs.ansible.com/ansible/latest/modules/win_chocolatey_module.html.
chocolatey_package 'fogapi' do
action :install
source 'INTERNAL REPO URL'
version '2411.9.17'
end
See docs at https://docs.chef.io/resource_chocolatey_package.html.
cChocoPackageInstaller fogapi
{
Name = "fogapi"
Version = "2411.9.17"
Source = "INTERNAL REPO URL"
}
Requires cChoco DSC Resource. See docs at https://github.com/chocolatey/cChoco.
package { 'fogapi':
ensure => '2411.9.17',
provider => 'chocolatey',
source => 'INTERNAL REPO URL',
}
Requires Puppet Chocolatey Provider module. See docs at https://forge.puppet.com/puppetlabs/chocolatey.
4. If applicable - Chocolatey configuration/installation
See infrastructure management matrix for Chocolatey configuration elements and examples.
This package was approved by moderator Windos on 26 Nov 2024.
FogApi Powershell Module Chocolatey Package
Requires Powershell 5.1+ (Core 7+ recommended).
This package installs the FogApi module in the AllUsers/System scope for:
- Powershell 7+ (C:\Program Files\Powershell\Modules\FogApi{version})
- Powershell 5.1 (C:\Program Files\WindowsPowershell\Modules\FogApi{version})
This ensures compatibility across pwsh versions (which are both included in Win11).
During default install, any other existing module versions are removed from both pwsh versions to avoid version conflicts.
The default uninstall behavior removes the specific module version of the given Chocolatey package.
You can customize this behavior with package parameters, though defaults are recommended.
Package Parameters
You can set the following parameters to alter the install behavior:
- /PS7Only: (true/false) - Install/uninstall only for Powershell 7. Defaults to false. Overwrites PS5Only if BOTH are true
- /PS5Only: (true/false) - Install/uninstall only for Powershell 5. Defaults to false.
- /NoRemove: (true/false) - (Install only) Do not remove other versions. Defaults to false.
- /RemoveAll: (true/false) - (Uninstall only) Uninstall all versions. Defaults to false.
Examples:
Install for Pwsh 7 only without removing other versions: choco install fogapi --params "'/PS7Only:true /NoRemove:true'"
Uninstall all versions: choco uninstall fogapi --params "'/RemoveAll'"
FOG Api Powershell Module
This is a powershell module to simplify the use of the Fog Project API.
This module is used to easily run Fog API commands on your fogserver from a powershell console or script.
FOG is an opensource tool for imaging comptuters, this module uses the API on your internal fog server to
perform almost any operation you can do in the GUI of Fog and provides you with the ability to extend things further.
It can be used to create more automation or to simply have a command line method of controlling fog operations.
This essentially gives you a crossplatform commandline interface for fog tasks and makes many things easier to automate.
Docs for this module can be found at https://fogapi.readthedocs.io/en/latest/
For more information about FOG see
- https://FOGProject.org
- https://docs.fogproject.org
- https://github.com/FOGProject
- https://github.com/FOGProject/fogproject
- https://forums.fogproject.org
Versioning
The versioning of this module follows this pattern
{Year|Month}.{Major Version}.{Revision #}
See https://github.com/darksidemilk/FogApi?tab=readme-ov-file#versioning for more info
Usage
You can use Set-fogserverSettings to set your fogserver hostname and api keys.
Or, the first time you try to run a command the settings.json file will automatically open in an OS Specific editor.
You can also open the settings.json file and edit it manually before running your first command.
The default settings are explanations of where to find the proper settings since json cannot have comments
Once the settings are set you can utilze the fog documentation found here https://news.fogproject.org/simplified-api-documentation/ that was used to model the parameters for Get-FogObject, Update-FogObject, and Remove-FogObject.
You can also utilize simpler functions of common tasks, see the links below for more info.
Additional info
- Examples and More: https://github.com/darksidemilk/FogApi/blob/master/README.md
- All Commands - https://fogapi.readthedocs.io/en/latest/commands/
- FogForums module thread: https://forums.fogproject.org/topic/12026/powershell-api-module/2
- Full change log available at https://fogapi.readthedocs.io/en/latest/ReleaseNotes/
{
"iis.configDir": ""
}$ErrorActionPreference = 'Stop'
#uninstall just this version of the module from system level paths
$toolsDir = Split-Path -parent $MyInvocation.MyCommand.Definition
#include the additional functions for install
Import-Module "$toolsDir\functions.psm1"
$moduleName = $env:chocolateyPackageName
$moduleVersion = $env:ChocolateyPackageVersion
$pp = Get-PackageParameters;
if (!($pp.PS7Only)) {
$pp.PS7Only = $false;
} else {
$pp.PS7Only = $true;
}
if (!($pp.PS5Only)) {
$pp.PS5Only = $false;
} else {
$pp.PS5Only = $true;
}
if (($pp.NoRemove)) {
Write-Warning "'NoRemove' was passed into uninstall, this parameter is only for install, this will be ignored"
$pp.NoRemove = $false;
} else {
$pp.NoRemove = $false;
}
if (!($pp.RemoveAll)) {
$pp.RemoveAll = $false;
} else {
$pp.RemoveAll = $true;
}
Remove-Module -Name $moduleName -force -ea 0;
if ($pp.RemoveAll) {
"Remove all specified, finding all versions of $modulename and removing them, is PS7Only or PS5Only is specified then only all versions from that path will be removed" | out-host;
Remove-ModuleManually -modulename $moduleName -ps5only:$pp.PS5Only -ps7only:$pp.PS7Only -allversions;
} else {
"Uninstalling module $modulename of version $moduleVersion" | out-host;
Remove-ModuleManually -modulename $moduleName -moduleversion $moduleVersion -ps5only:$pp.PS5Only -ps7only:$pp.PS7Only;
}
function Grant-FullRightsToPath {
<#
.SYNOPSIS
Use icacls to grant full rights to a user or users of a given path or paths
.DESCRIPTION
Loops through given paths and users and grants full access to the given paths for the given users
uses icacls $path /grant username:F /T /C for explicit permissions, or uses inhertiable permissions on parent with -inherit
You should send all paths without trailing slashes, but if you forget, the trailing slash will be removed for you.
Unless you specify the -wait switch, the icacls processes will all start in the background. If you specify -wait each process will wait before the next is started
The -wait or -waitoutput switch will display a string of all the output at the end of the function, a list object of the generated logs with the results is always returned.
The result logs are stored in C:\logs\perms and have a syntax of the path(with - instead of \)_userOrGroup.log
i.e. if one of your paths
.PARAMETER path
The path, or list of paths, to set permissions on
.PARAMETER user
The user/group or list of users/groups to give full permission to the given paths
Defaults to Authenticated Users group. If it is a domain user or group, it needs "DOMAIN\common name" syntax
Usernames and groups can have spaces if they are enclosed in ""
.PARAMETER inherit
Switch param to enable inheritance, when specified it will only enable the inheritable permissions on the parent folder
If not specified, it will set the permissions explicitly on each file.
IF you also enabled -recurseInherit then the recurse behavior overrides the only setting on the parent folder behavior
.PARAMETER recurseInherit
Switch param to enable inheritance, when specified it will enable inheritable permissions on the parent folder and all subfolders and files.
This is typically not neccesarry over normal inherit but is provided as an option for flexibility
This switch can be enabled with or without the -inherit switch
.PARAMETER wait
switch to enable waiting for each icacls process to finish before starting the next. When this is enabled, a string output of the logs will be displayed at the end
.PARAMETER waitOutput
Switch to enable a wait at the end of the function for all running icacls to finish, and then generate and display a string output
.EXAMPLE
Grant-FullRightsToPath -path "C:\Program Files\WindowsPowershell\Modules\FogApi","C:\Program Files\Powershell\Modules\FogApi" -user "Authenticated Users"
This will give the authenticated users group full access to the install folder of the FogAPI module
This helps during install/uninstall/update of the module. The settings.json file that contains the api key is stored elsewhere per user
.NOTES
This is a simple wrapper for a common use of icacls. This is the help info for icacls:
ICACLS name /save aclfile [/T] [/C] [/L] [/Q]
stores the DACLs for the files and folders that match the name
into aclfile for later use with /restore. Note that SACLs,
owner, or integrity labels are not saved.
ICACLS directory [/substitute SidOld SidNew [...]] /restore aclfile
[/C] [/L] [/Q]
applies the stored DACLs to files in directory.
ICACLS name /setowner user [/T] [/C] [/L] [/Q]
changes the owner of all matching names. This option does not
force a change of ownership; use the takeown.exe utility for
that purpose.
ICACLS name /findsid Sid [/T] [/C] [/L] [/Q]
finds all matching names that contain an ACL
explicitly mentioning Sid.
ICACLS name /verify [/T] [/C] [/L] [/Q]
finds all files whose ACL is not in canonical form or whose
lengths are inconsistent with ACE counts.
ICACLS name /reset [/T] [/C] [/L] [/Q]
replaces ACLs with default inherited ACLs for all matching files.
ICACLS name [/grant[:r] Sid:perm[...]]
[/deny Sid:perm [...]]
[/remove[:g|:d]] Sid[...]] [/T] [/C] [/L] [/Q]
[/setintegritylevel Level:policy[...]]
/grant[:r] Sid:perm grants the specified user access rights. With :r,
the permissions replace any previously granted explicit permissions.
Without :r, the permissions are added to any previously granted
explicit permissions.
/deny Sid:perm explicitly denies the specified user access rights.
An explicit deny ACE is added for the stated permissions and
the same permissions in any explicit grant are removed.
/remove[:[g|d]] Sid removes all occurrences of Sid in the ACL. With
:g, it removes all occurrences of granted rights to that Sid. With
:d, it removes all occurrences of denied rights to that Sid.
/setintegritylevel [(CI)(OI)]Level explicitly adds an integrity
ACE to all matching files. The level is to be specified as one
of:
L[ow]
M[edium]
H[igh]
Inheritance options for the integrity ACE may precede the level
and are applied only to directories.
/inheritance:e|d|r
e - enables inheritance
d - disables inheritance and copy the ACEs
r - remove all inherited ACEs
Note:
Sids may be in either numerical or friendly name form. If a numerical
form is given, affix a * to the start of the SID.
/T indicates that this operation is performed on all matching
files/directories below the directories specified in the name.
/C indicates that this operation will continue on all file errors.
Error messages will still be displayed.
/L indicates that this operation is performed on a symbolic link
itself versus its target.
/Q indicates that icacls should suppress success messages.
ICACLS preserves the canonical ordering of ACE entries:
Explicit denials
Explicit grants
Inherited denials
Inherited grants
perm is a permission mask and can be specified in one of two forms:
a sequence of simple rights:
N - no access
F - full access
M - modify access
RX - read and execute access
R - read-only access
W - write-only access
D - delete access
a comma-separated list in parentheses of specific rights:
DE - delete
RC - read control
WDAC - write DAC
WO - write owner
S - synchronize
AS - access system security
MA - maximum allowed
GR - generic read
GW - generic write
GE - generic execute
GA - generic all
RD - read data/list directory
WD - write data/add file
AD - append data/add subdirectory
REA - read extended attributes
WEA - write extended attributes
X - execute/traverse
DC - delete child
RA - read attributes
WA - write attributes
inheritance rights may precede either form and are applied
only to directories:
(OI) - object inherit
(CI) - container inherit
(IO) - inherit only
(NP) - don't propagate inherit
(I) - permission inherited from parent container
Examples:
icacls c:\windows\* /save AclFile /T
- Will save the ACLs for all files under c:\windows
and its subdirectories to AclFile.
icacls c:\windows\ /restore AclFile
- Will restore the Acls for every file within
AclFile that exists in c:\windows and its subdirectories.
icacls file /grant Administrator:(D,WDAC)
- Will grant the user Administrator Delete and Write DAC
permissions to file.
icacls file /grant *S-1-1-0:(D,WDAC)
- Will grant the user defined by sid S-1-1-0 Delete and
Write DAC permissions to file.
#>
[CmdletBinding()]
param (
[string[]]$path,
[string[]]$user = (@("Authenticated Users")),
[switch]$inherit,
[switch]$wait,
[switch]$waitOutput,
[switch]$recurseInherit,
[switch]$noOutHost
)
process {
$output = "";
$prcs = New-List;
$logs = New-List;
if (!$noOutHost) {
"Setting full access permissions for given paths to given users...." | Out-Host;
}
Write-Verbose "Setting full access permissions for given paths:`n$($path)`nto given users`n$($user)`n...."
$path | ForEach-Object {
$pth = "$($_)"
$logBase = "C:\logs\perms"
New-Dir $logBase | Out-Null;
if ($pth[-1] -eq '\') {
if (!$noOutHost) {
"Removing trailing slash from $pth for parsing" | Out-Host;
}
$pth = $pth.TrimEnd("\");
}
if (Test-Path $pth) {
$itm = $pth.replace(":","-").replace("\","-");
$user | ForEach-Object {
$curUsr = $_;
$log = "$logBase\$itm`_$($curUsr.replace("\","-")).log";
New-Item -ItemType File -path $log -force -ea 0;
$logs.add($log);
if ($inherit -or $recurseInherit) {
if ($recurseInherit) {
$argStr = "`"$pth`" /inheritance:e /grant `"$curUsr`:(OI)(CI)(F)`" /T /C /Q"
} else {
$argStr = "`"$pth`" /inheritance:e /grant `"$curUsr`:(OI)(CI)(F)`" /C /Q"
}
Write-Verbose "Setting inheritable permissions on $pth for user/group $curUsr`:`n"
} else {
$argStr = "`"$pth`" /grant `"$curUsr`:(F)`" /T /C /Q"
Write-Verbose "Setting explicit permissions on all files in $pth for user/group $curUsr`:`n"
}
# "Setting permissions on $pth for user $curUsr" | Out-Host;
$prc = start-process -FilePath icacls.exe -args $argStr -NoNewWindow -RedirectStandardOutput $log -PassThru -wait:$wait.IsPresent -ea 0;
$prcs.add($prc)
Write-Verbose "$($prc | out-string) for $log is started";
try {
if ((get-content $log -raw) -match "No mapping between account names and security IDs was done") {
throw "user $curUsr is invalid!"
return $error[0];
}
} catch {
Write-Verbose "not able to test for user validation"
}
}
} else {
throw "path $pth does not exist!"
return $error[0];
}
}
if (!$wait -AND $waitOutput) {
if (!$noOutHost) {
"waiting on icacls processes to finish...." | Out-Host;
}
$prcs | ForEach-Object {
if ($_.hasexited) {
Write-Verbose "process is already ended"
} else {
try {
while (!$_.hasexited) {
start-sleep -milliseconds 10
}
} catch {
Write-Verbose "process is already ended"
}
}
}
}
if ($waitOutput -or $wait) {
if (!$noOutHost) {
$output = "`nResults of icacls from logs:`n`n"
$logs | ForEach-Object {
# $output += "`n______________________________`n"
$output += $_;
$output += "`n______________________________`n`n"
$output += Get-Content $_ -raw;
$output += "`n------------------------------`n`n`n"
}
$output | Out-Host;
}
}
return $logs;
}
}
function Remove-ModuleManually {
[CmdletBinding()]
param (
$modulename,
$moduleversion,
[switch]$ps5only,
[switch]$ps7only,
[switch]$allversions
)
process {
$destinationPath = @()
if ($allversions) {
#if removing all versions, just remove the top level path, get the top level path per the be
$moduleversion = $null;
}
if($ps7only) {
$destinationPath += Join-Path -Path $env:ProgramFiles -ChildPath "WindowsPowerShell\Modules\$moduleName\$moduleVersion"
} elseif ($ps5only) {
$destinationPath += Join-Path -Path $env:ProgramFiles -ChildPath "PowerShell\Modules\$moduleName\$moduleVersion"
} else {
$destinationPath += Join-Path -Path $env:ProgramFiles -ChildPath "WindowsPowerShell\Modules\$moduleName\$moduleVersion"
$destinationPath += Join-Path -Path $env:ProgramFiles -ChildPath "PowerShell\Modules\$moduleName\$moduleVersion"
}
$destinationPath | ForEach-Object {
$destpath = $_;
if (Test-path $destPath) {
Write-verbose "Taking ownership of path $($destpath) and setting permissions to ensure clean removal";
$logDir = "$env:temp\logs"
if (!(Test-Path $logDir)) {
mkdir $logDir -ea 0;
}
$takeOwn = start-process -FilePath takeown.exe -ArgumentList "/F `"$($destPath)`" /R /A /D Y" -wait -NoNewWindow -PassThru -RedirectStandardOutput "$logDir\takeown-$modulename-paths.log"
Write-Verbose "Take Ownership result is $($takeOwn | out-string) - $(Get-content "$logDir\takeown-$modulename-paths.log" | out-string)"
#no need to keep the redirected output log that was output in verbose
Remove-Item "$logDir\takeown-$modulename-paths.log" -force -Recurse -ea 0;
try {
#give full rights to path being deleted to authenticated users
$perms = Grant-FullRightsToPath -path $destPath -recurseInherit -ea stop -wa 0 -wait -NoOutHost
Write-Verbose "grant result is $($perms | out-string)"
} catch {
$perms = icacls "$($destPath)" /inheritance:e /grant "Authenticated Users:(OI)(CI)(F)" /T /C /Q
Write-Verbose "Grant-fullrightstopath had an error, icacls native grant result is $($perms | out-string)"
}
try {
if (Test-Path $destpath) {
Write-Verbose "Attempting removal of version $moduleVersion of $moduleName installed at $($destpath)"
[gc]::collect()
[gc]::waitforpendingfinalizers()
[gc]::collect()
Remove-Item -Path $destpath -Force -Recurse -EA stop;
} else {
"No install for $modulename found at $($destpath)" | out-host;
}
} catch {
Write-Warning "Version of $moduleName at $($destpath) could not be removed, most likely a dll was still loaded, attempting removal of all but dlls"
Get-ChildItem $destpath -Exclude "*.dll" -Recurse | ForEach-Object {
Remove-Item -path $destpath.FullName -force -ea 0;
}
}
}
if (!$allversions) {
#check if no other versions exist
if ((Get-ChildItem ($destpath | Split-Path -Parent) -Directory -ea 0).count -eq 0) {
Write-Warning "no versions remaining in $(($destpath | Split-Path -Parent).fullname) attempting to remove parent folder"
($destpath | Split-Path -Parent) | Remove-Item -Force -Recurse -ea 0
}
}
}
}
} Log in or click on link to see number of positives.
- FogApi.2411.9.17.nupkg (491049138036) - ## / 65
- fogapi.2411.9.17.IncludeXml.zip (fbd17c1f156a) - ## / 67
In cases where actual malware is found, the packages are subject to removal. Software sometimes has false positives. Moderators do not necessarily validate the safety of the underlying software, only that a package retrieves software from the official distribution point and/or validate embedded software against official distribution point (where distribution rights allow redistribution).
Chocolatey Pro provides runtime protection from possible malware.
| Add to Builder | Version | Downloads | Last Updated | Status |
|---|---|---|---|---|
| FogApi Powershell Module 2411.9.17 | 21 | Sunday, November 17, 2024 | Approved | |
| FogApi Powershell Module 2408.9.3 | 48 | Monday, September 23, 2024 | Approved |
2018-2024
2411.9.17
Update receive-fogimage and test choco publish (#31)
Fix some typos in descriptions and add step in Remove-ModuleManually to remove the parent install folder if no other versions exist.
Update README.md
markdown fixes and spell checking
Add error handling if a module path doesn't exist for choco package install template
Should resolve Add pipeline and task options to Receive-FogImage #29
Full change log history available at https://fogapi.readthedocs.io/en/latest/ReleaseNotes/
This package has no dependencies.
Ground Rules:
- This discussion is only about FogApi Powershell Module and the FogApi Powershell Module package. If you have feedback for Chocolatey, please contact the Google Group.
- This discussion will carry over multiple versions. If you have a comment about a particular version, please note that in your comments.
- The maintainers of this Chocolatey Package will be notified about new comments that are posted to this Disqus thread, however, it is NOT a guarantee that you will get a response. If you do not hear back from the maintainers after posting a message below, please follow up by using the link on the left side of this page or follow this link to contact maintainers. If you still hear nothing back, please follow the package triage process.
- Tell us what you love about the package or FogApi Powershell Module, or tell us what needs improvement.
- Share your experiences with the package, or extra configuration or gotchas that you've found.
- If you use a url, the comment will be flagged for moderation until you've been whitelisted. Disqus moderated comments are approved on a weekly schedule if not sooner. It could take between 1-5 days for your comment to show up.