NOTE: We are currently NOT accepting PRs for this project
Collection of Posix tools wrappers.
This module intends to make managing Linux or Unix systems easier for PowerShell users. It does so by:
[nxLocalUser]
, [nxLocalGroup]
, [nxFile]
, removing the need for parsing.On a fresh clone, you should be able to get by after installing GitVersion by building like so:
build.ps1 -Tasks build
This will build the nxtools module in your output/module
folder.
Should you want to build the Machine Configuration package, run the following instead:
build.ps1 -Tasks gcpol
PowerShell must be installed on your system.
To build this project, GitVersion is recommended to build the right version according to your git status.
You can install nxtools
module from the PowerShell Gallery:
Install-Module -Name nxtools
The goal is to help handle the most common tasks:
Here are the public commands available.
Compress-nxArchive
: Create an archive and add files and folders to it.Expand-nxArchive
: Expand the file and folders out of an archive.Add-nxFileLine
: Append or insert a line if it's not present. The line can be inserted before or after a pattern is found in the file.Invoke-nxFileContentReplace
: Edit a file by searching for a pattern, and replacing it by an expression or script block. This can also be done over multiple line to replace several lines in one run.Remove-nxFileLine
: Remove specific lines from a file by line number. You can use this with Select-String
to know which line to remove. Get-nxItem
: Similar to Get-Item for file system provider but on Linux using ls -d
.Get-nxChildItem
: Similar to Get-ChildItem for the FileSystem provider but on Linux, this will use the ls
command.Compare-nxFileSystemMode
: An easy way to compare two sets of unix file system permissions.rwxrwxrwx
), or the numericla permission (777
or 0777
).Set-nxMode
: Set files and folder mode (permisisons) using chmod
.Set-nxOwner
: Set the owner for files and folders (and optionally the group ownership) using chown
.Set-nxGroupOwnership
: Set the group owning the files and folders using chgrp
.Get-nxLocalUser
: Read and parse local users from /etc/passwd
.Get-nxLocalGroup
: Read and parse local groups from /etc/group
.Get-nxLocalUserMemberOf
: Get the groups ([nxLocalGroup[]]
) a Local user is member of.New-nxLocalUser
: Creates a new Local User using useradd
.Add-nxLocalGroupMember
: Add users to a group using gpasswd
.Add-nxLocalUserToGroup
: Add user to groups using usermod
.New-nxLocalGroup
: Create a new Local Group using groupadd
.Set-nxLocalGroup
: Set the properties of an existing local group using gpasswd
.Set-nxLocalGroupMember
: Set (and replace) the members of an existing group using gpasswd
.Remove-nxLocalUser
: Delete a Local user using userdel
.Remove-nxLocalGroupMember
: Removes users from a local group using gpasswd
.Remove-nxLocalGroup
: Deletes a local group using groupdel
.Get-nxEtcShadow
: Gets a user's /etc/shadow
entry if it exists.Disable-nxLocalUser
: Lock a user's password, Expire its account and replace its Shell to /sbin/nologin
.Get-nxKernelInfo
: A simple wrapper around uname -a
.Get-nxLinuxStandardBaseRelease
: A quick wrap of lsb_release -a
command (this lsb_release
must be present on the system).Get-nxDistributionInfo
: Parsing information found in /etc/*-release
.nxFile
: Manage a file or a folder to make sure it's present/absent, its content, mode, owner group.nxGroup
: Simple resource to manage [nxLocalGroup] and group members.nxUser
: Simple resource to manage [nxLocalUser] accounts.nxPackage
: Audit (for now) whether a package is installed or not in a system (currently supports apt only).nxFileLine
: Ensure an exact line is present/absent in a file, and remediate by appending, inserting, deleting as needed.nxFileContentReplace
: Replace the content in a file if a pattern is found.nxService
: Simple resource for managing services on a Linux node (currently supports systemd only).nxScript
: Simple resource for executing scripts in PowerShell 7.No90CloudInitUserAllowdNoPasswdInSudoers
: Ensure no user are granted NOPASSWD in sudoers file /etc/sudoers.d/90-cloud-init-users
.InstalledApplicationLinux
[Audit
]: Ensure the list of packages is installed (dpkg only)LinuxGroupsMustExclude
[AuditAndSet
]: List of users that must be excluded from a group.LinuxGroupsMustInclude
[AuditAndSet
]: List of users that must be included in a group.NotInstalledApplicationLinux
[Audit
]: Ensure the list of packages is not installed (dpkg only)PasswordPolicy_msid110
[Audit
]: Remote connections from accounts with empty passwords should be disabled.PasswordPolicy_msid121
[Audit
]: file /etc/passwd
permissions should be 0644PasswordPolicy_msid232
[Audit
]: Ensure there are no accounts without passwords.
Get-nxKernelInfo # uname -a
Get-nxDistributionInfo # cat /etc/*-release
Get-nxLinuxStandardBaseRelease # lsb_release -a (not available by default on some Debian 10, Alpine and others)
Get-nxLocalUser # cat /etc/passwd
Get-nxLocalUser -UserName (whoami)
Get-nxLocalUser -Pattern '^gcolas$'
Get-nxLocalGroup # cat /etc/group
Get-nxLocalGroup tape | Get-nxLocalUser
Get-nxItem /tmp/testdir
(Get-nxItem /tmp/testdir).Mode
(Get-nxItem /tmp/testdir).Mode.ToString()
(Get-nxItem /tmp/testdir).Mode.ToOctal()
# using module output/nxtools
# using module nxtools
[nxFileSystemMode]'rwxr--r--'
[nxFileSystemMode]'ugo=rwx'
[nxFileSystemMode]'1777'
[nxFileSystemMode]'u=rwx g=r o=r'
# Proper handling of symbolic links not yet implemented
Compare-nxMode -ReferenceMode 'r--r--r--' -DifferenceMode 1777 | FT -a
Get-nxChildItem -Path /tmp/testdir | Compare-nxMode -ReferenceMode 'r--r--r--' | FT -a
Get-nxChildItem /tmp/testdir/ -File | FT -a
Get-nxChildItem /tmp/testdir/ -Directory | FT -a
Get-nxChildItem /tmp/testdir/ | FT -a
Get-nxChildItem /tmp/testdir/ -File | Move-Item -Destination /tmp/testdir/otherdir/ -Verbose
Get-nxChildItem /tmp/testdir/ -File | FT -a
Get-nxChildItem /tmp/testdir/ -File -recurse | FT -a
Set-nxMode -Path /tmp/tmpjBneMD.tmp -Mode 'rwxr--r--' -Recurse -WhatIf # chmod -R 0744
Set-nxMode -Path /tmp/tmpjBneMD.tmp -Mode '0744' -Recurse -WhatIf # chmod -R 0744
Set-nxMode -Path /tmp/tmpjBneMD.tmp -Mode 744 -Recurse -Whatif # chmod -R 0744
# Get the other groups the members of the tape group are member of
Get-nxLocalGroup tape | Get-nxLocalUser | Get-nxLocalUserMemberOf
Set-nxOwner -Path /tmp/tmpjBneMD.tmp -Owner (whoami) # chown gcolas /tmp/tmpjBnedMD.tmp
Set-nxGroupOwnership -Path /tmp/testdir -Recurse -Group users -RecursivelyTraverseSymLink
Integration tests can be run on Azure VMs using Test-Kitchen with the kitchen yaml provided. More details will be added.
HQRM tests can be run like so:
build.ps1 -Tasks build,hqrmtest
N/A: End to end tests integrated with Guest Config are not yet implemented.
Integration tests using Test-Kitchen
Deployment is privately done after QA checks.
Please read our CONTRIBUTING.md which outlines all of our policies, procedures, and requirements for contributing to this project.
Currently, we cannot accept contributions.
We use SemVer version 2.0 for versioning. For the versions available, see the PSGallery.
It is a good practice to keep CHANGELOG.md
file in repository that can be updated as part of a pull request.
This project is licensed under the MIT - see the LICENSE file for details.
This module is intended to provide guidelines / samples to help authors to create their own configurations and resource modules for use in custom Machine Configuration projects.
Support is best effort via GitHub issues. If there are any questions and comments, we will try to get to them but may not be able to.
We are not currently accepting PRs.
Further, the machine configuration artifact build process is private, so the only feedback we can provide on a public PR is functional testing. We will have to do a full private integration test before merging.
This project was created by Gael Colas, who was a contractor working with Microsoft.
The third-party tools we are using that are nested in this module are PSNativeCmdDevKit and DscResource.Common from the DSC Community. All the other tools mentioned are only for building and testing.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.
nxtools
PSGallery package.