diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json deleted file mode 100644 index e4b4c5783a..0000000000 --- a/.config/dotnet-tools.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "version": 1, - "isRoot": true, - "tools": { - "cake.tool": { - "version": "1.1.0", - "commands": [ - "dotnet-cake" - ] - } - } -} \ No newline at end of file diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile deleted file mode 100644 index c5a3748a73..0000000000 --- a/.devcontainer/Dockerfile +++ /dev/null @@ -1,5 +0,0 @@ -ARG VARIANT="3.1-focal" -FROM mcr.microsoft.com/vscode/devcontainers/dotnet:0-${VARIANT} - -ARG NODE_VERSION="20" -RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi \ No newline at end of file diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 0b3f58e710..84aaed0d14 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,27 +1,34 @@ // For format details, see https://aka.ms/devcontainer.json. For config options, see the README at: -// https://github.com/microsoft/vscode-dev-containers/tree/v0.202.5/containers/dotnet +// https://github.com/withastro/astro/blob/main/.devcontainer/with-mdx/devcontainer.json { - "name": "C# (.NET)", - "runArgs": ["--init"], - "build": { - "dockerfile": "Dockerfile", - "args": { - "VARIANT": "3.1-focal", - "NODE_VERSION": "20" + "name": "Node.js & TypeScript", + "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bullseye", + "forwardPorts": [5086], + "portsAttributes": { + "5086": { + "label": "Astro", + "onAutoForward": "openBrowser" + } + }, + "postAttachCommand": "yarn dev", + "customizations": { + "codespaces": { + "openFiles": ["README.md"] + }, + "vscode": { + "extensions": [ + "DavidAnson.vscode-markdownlint", + "shardulm94.trailing-spaces", + "nhoizey.gremlins", + "streetsidesoftware.code-spell-checker", + "bierner.emojisense", + "astro-build.astro-vscode", + "esbenp.prettier-vscode", + "unifiedjs.vscode-mdx", + "ms-vscode.vscode-typescript-next", + "dbaeumer.vscode-eslint" + ] } - }, - "hostRequirements": { - "cpus": 4, - "memory": "8gb" - }, - "settings": {}, - "extensions": [ - "ms-dotnettools.csharp", - "DavidAnson.vscode-markdownlint", - "shardulm94.trailing-spaces", - "nhoizey.gremlins", - "streetsidesoftware.code-spell-checker", - "bierner.emojisense" - ], - "remoteUser": "vscode" + }, + "remoteUser": "node" } diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000000..0dbaa9b227 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,54 @@ +# build output +dist/ + +# generated types +.astro/ + +# dependencies +node_modules/ + +# git history +.git + +# logs +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + +# npm +npm-debug.log +.coverage +.coverage.* +.env +.aws + +# yarn +.pnp.* +.yarn/* +!.yarn/patches +!.yarn/plugins +!.yarn/releases +!.yarn/sdks +!.yarn/versions + +# environment variables +.env +.env.production + +# macOS-specific files +.DS_Store + +# jetbrains setting folder +.idea/ + +# choco-theme +public/fonts +public/scripts +public/styles +public/images/global-shared + +# general +apple-touch-*.png +favicon.ico +.astro diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000000..ffe9a1f4fd --- /dev/null +++ b/.editorconfig @@ -0,0 +1,10 @@ +root = true + +[*] +end_of_line = lf +insert_final_newline = true + +[*.{js,json,yml}] +charset = utf-8 +indent_style = space +indent_size = 4 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000000..af3ad12812 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +/.yarn/** linguist-vendored +/.yarn/releases/* binary +/.yarn/plugins/**/* binary +/.pnp.* binary linguist-generated diff --git a/.github/workflows/playwright.yml b/.github/workflows/playwright.yml new file mode 100644 index 0000000000..dfea630d8e --- /dev/null +++ b/.github/workflows/playwright.yml @@ -0,0 +1,27 @@ +name: Playwright Tests + +on: + pull_request: + branches: [ main, master ] + workflow_dispatch: +jobs: + test: + timeout-minutes: 60 + runs-on: ubuntu-latest + steps: + - name: Checkout repository using git + uses: actions/checkout@v4 + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + - name: Build site + run: yarn build + - name: Run Playwright tests + run: yarn playwright + - uses: actions/upload-artifact@v4 + if: always() + with: + name: playwright-report + path: playwright-report/ + retention-days: 14 diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml index e431ce8d39..bfba5ac6b8 100644 --- a/.github/workflows/publish.yaml +++ b/.github/workflows/publish.yaml @@ -1,37 +1,32 @@ name: Publish Documentation -on: - workflow_dispatch: - push: - branches: - - master -jobs: +on: + push: + branches: [ master ] + workflow_dispatch: - ################################################### - # DOCS - ################################################### +# Allow this job to clone the repo and create a page deployment +permissions: + contents: read + pages: write + id-token: write +jobs: build: - name: Publish - runs-on: windows-latest + runs-on: ubuntu-latest steps: - - name: Checkout - uses: actions/checkout@v2 - with: - fetch-depth: 0 - - - name: Setup dotnet - uses: actions/setup-dotnet@v1 - with: - dotnet-version: '3.1.301' # SDK Version to use. + - name: Checkout repository using git + uses: actions/checkout@v4 + - name: Install, build, and upload site + uses: withastro/action@v2 - - name: Publish-Documentation - shell: bash - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - STATIQ_GITHUB_TOKEN: ${{ secrets.STATIQ_GITHUB_TOKEN }} - STATIQ_DEPLOY_BRANCH: ${{ secrets.STATIQ_DEPLOY_BRANCH }} - STATIQ_DEPLOY_REMOTE: ${{ secrets.STATIQ_DEPLOY_REMOTE }} - run: | - dotnet tool restore - dotnet cake --target=Publish-Documentation \ No newline at end of file + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/.github/workflows/pullrequest.yaml b/.github/workflows/pullrequest.yaml deleted file mode 100644 index f3a9c28549..0000000000 --- a/.github/workflows/pullrequest.yaml +++ /dev/null @@ -1,31 +0,0 @@ -name: Build Pull Request -on: - pull_request: - -jobs: - - ################################################### - # DOCS - ################################################### - - build: - name: Build - runs-on: windows-latest - steps: - - name: Checkout - uses: actions/checkout@v2 - with: - fetch-depth: 0 - - - name: Setup dotnet - uses: actions/setup-dotnet@v1 - with: - dotnet-version: '3.1.301' # SDK Version to use. - - - name: Statiq-Build - shell: bash - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - dotnet tool restore - dotnet cake --target=Statiq-Build \ No newline at end of file diff --git a/.gitignore b/.gitignore index 742ea927b5..90a8406481 100644 --- a/.gitignore +++ b/.gitignore @@ -1,21 +1,26 @@ -.dotnet/ -tools/ -BuildArtifacts/ -config.wyam.* -.DS_Store -output/ -bin/ -obj/ -publish/ +# build output +dist/ + +# generated types +.astro/ + +# dependencies node_modules/ -input/assets/css/ -input/assets/js/ -input/assets/fonts/ -input/assets/images/global-shared/ -input/global-partials/ -apple-touch-*.png -favicon.ico -cache/ + +# logs +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + +# npm +npm-debug.log +.coverage +.coverage.* +.env +.aws + +# yarn .pnp.* .yarn/* !.yarn/patches @@ -23,4 +28,31 @@ cache/ !.yarn/releases !.yarn/sdks !.yarn/versions -.directory \ No newline at end of file + +# environment variables +.env +.env.production + +# macOS-specific files +.DS_Store + +# jetbrains setting folder +.idea/ + +# choco-theme +public/fonts +public/scripts +public/styles +public/images/global-shared + +# general +apple-touch-*.png +favicon.ico +.astro + +# playwright +/src/tests/ +/test-results/ +/playwright-report/ +/blob-report/ +/playwright/.cache/ diff --git a/.markdownlint.json b/.markdownlint.json index 2034cef932..d52120e02e 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -1,9 +1,9 @@ { - "MD026": false, - "MD013": false, - "MD024": false, - "MD034": false, - "MD033": { - "allowed_elements": ["details", "strong", "summary"] - } -} + "MD026": false, + "MD013": false, + "MD024": false, + "MD034": false, + "MD033": { + "allowed_elements": ["details", "strong", "summary"] + } +} \ No newline at end of file diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000000..22a15055d6 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,4 @@ +{ + "recommendations": ["astro-build.astro-vscode"], + "unwantedRecommendations": [] +} diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000000..d642209762 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,11 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "command": "./node_modules/.bin/astro dev", + "name": "Development server", + "request": "launch", + "type": "node-terminal" + } + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json index b7ba3b08dc..37743adeae 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,130 +1,149 @@ { - "cSpell.words": [ - "Admins", - "adobereader", - "Authenticode", - "baretail", - "baselined", - "behavior", - "Boxstarter", - "choco", - "chococcm", - "Chocolatey's", - "chocolateyorg", - "chocolateypackage", - "Cloudsmith", - "cmdlet", - "crapware", - "cygwin", - "digicert", - "Disqus", - "distro", - "distros", - "Emoji", - "exes", - "fullname", - "gemcutter", - "gitextensions", - "Gitter", - "HKEY", - "HKLM", - "honor", - "Internalizer", - "Intune", - "intunewin", - "Kickstarter", - "labeouf", - "LASTEXITCODE", - "malware", - "minecraft", - "MITM", - "MSIX", - "myget", - "Ninite", - "notepadplusplus", - "nuget", - "nupkg", - "packagename", - "packageparameters", - "pkgid", - "pkgname", - "programdata", - "psobject", - "qdeazure", - "rebundle", - "Roadmap", - "Saltstack", - "SCCM", - "scriptable", - "shia", - "Sonatype", - "sphynx", - "Statiq", - "sysadmins", - "TLDR", - "uninstallation", - "Uninstaller", - "Uninstalling", - "uninstalls", - "versioningupgrades", - "webpi", - "whatif", - "windirstat", - "xcopy" - ], - "languageToolLinter.languageTool.ignoredWordsInWorkspace": [ - "format-filesize", - "get-packageparameters", - "choco-info", - "choco-warning", - "chocolatey", - "chocolateyinstall", - "format-filesize", - "get-checksumvalid", - "get-chocolateyconfigvalue", - "get-chocolateypath", - "get-chocolateyunzip", - "get-chocolateywebfile", - "get-environmentvariable", - "get-environmentvariablenames", - "get-ftpfile", - "get-osarchitecturewidth", - "get-packageparameters", - "get-toolslocation", - "get-uacenabled", - "get-uninstallregistrykey", - "get-viruscheckvalid", - "get-webfile", - "get-webfilename", - "get-webheaders", - "install-binfile", - "install-chocolateyenvironmentvariable", - "install-chocolateyexplorermenuitem", - "install-chocolateyfileassociation", - "install-chocolateyinstallpackage", - "install-chocolateypackage", - "install-chocolateypath", - "install-chocolateypinnedtaskbaritem", - "install-chocolateypowershellcommand", - "install-chocolateyshortcut", - "install-chocolateyvsixpackage", - "install-chocolateywindowsservice", - "install-chocolateyzippackage", - "install-vsix", - "qde", - "set-environmentvariable", - "set-powershellexitcode", - "sonatype", - "start-chocolateyprocessasadmin", - "start-chocolateywindowsservice", - "stop-chocolateywindowsservice", - "test-processadminrights", - "uninstall-binfile", - "uninstall-chocolateyenvironmentvariable", - "uninstall-chocolateypackage", - "uninstall-chocolateywindowsservice", - "uninstall-chocolateyzippackage", - "update-sessionenvironment", - "write-functioncalllogmessage" - ] + "cSpell.words": [ + "Admins", + "adobereader", + "amped", + "Anson", + "astro", + "astrojs", + "authenticode", + "Authenticode", + "baretail", + "baselined", + "behavior", + "bierner", + "Boxstarter", + "Callout", + "Checksumming", + "choco", + "chococcm", + "Chocolatey's", + "chocolateyorg", + "chocolateypackage", + "Cloudsmith", + "cmdlet", + "Codespaces", + "crapware", + "cygwin", + "datetime", + "dbaeumer", + "devcontainers", + "digicert", + "Disqus", + "distro", + "distros", + "Emoji", + "emojisense", + "esbenp", + "exes", + "fullname", + "gemcutter", + "gitextensions", + "Gitter", + "HKEY", + "HKLM", + "honor", + "Internalizer", + "Intune", + "intunewin", + "Kickstarter", + "labeouf", + "LASTEXITCODE", + "malware", + "minecraft", + "MITM", + "MSIX", + "myget", + "nhoizey", + "Ninite", + "nocheck", + "notepadplusplus", + "nuget", + "nupkg", + "packagename", + "packageparameters", + "pkgid", + "pkgname", + "programdata", + "psobject", + "qdeazure", + "rebundle", + "rehype", + "Roadmap", + "Saltstack", + "SCCM", + "scriptable", + "shardulm", + "shia", + "Sonatype", + "sphynx", + "Statiq", + "sysadmins", + "TLDR", + "unifiedjs", + "uninstallation", + "Uninstaller", + "Uninstalling", + "uninstalls", + "versioningupgrades", + "webpi", + "whatif", + "windirstat", + "xcopy" + ], + "languageToolLinter.languageTool.ignoredWordsInWorkspace": [ + "format-filesize", + "get-packageparameters", + "choco-info", + "choco-warning", + "chocolatey", + "chocolateyinstall", + "format-filesize", + "get-checksumvalid", + "get-chocolateyconfigvalue", + "get-chocolateypath", + "get-chocolateyunzip", + "get-chocolateywebfile", + "get-environmentvariable", + "get-environmentvariablenames", + "get-ftpfile", + "get-osarchitecturewidth", + "get-packageparameters", + "get-toolslocation", + "get-uacenabled", + "get-uninstallregistrykey", + "get-viruscheckvalid", + "get-webfile", + "get-webfilename", + "get-webheaders", + "install-binfile", + "install-chocolateyenvironmentvariable", + "install-chocolateyexplorermenuitem", + "install-chocolateyfileassociation", + "install-chocolateyinstallpackage", + "install-chocolateypackage", + "install-chocolateypath", + "install-chocolateypinnedtaskbaritem", + "install-chocolateypowershellcommand", + "install-chocolateyshortcut", + "install-chocolateyvsixpackage", + "install-chocolateywindowsservice", + "install-chocolateyzippackage", + "install-vsix", + "qde", + "set-environmentvariable", + "set-powershellexitcode", + "sonatype", + "start-chocolateyprocessasadmin", + "start-chocolateywindowsservice", + "stop-chocolateywindowsservice", + "test-processadminrights", + "uninstall-binfile", + "uninstall-chocolateyenvironmentvariable", + "uninstall-chocolateypackage", + "uninstall-chocolateywindowsservice", + "uninstall-chocolateyzippackage", + "update-sessionenvironment", + "write-functioncalllogmessage" + ] } \ No newline at end of file diff --git a/.yarnrc.yml b/.yarnrc.yml index afcc04f9fb..ca9fc37d06 100644 --- a/.yarnrc.yml +++ b/.yarnrc.yml @@ -1,5 +1,5 @@ -checksumBehavior: update - -nodeLinker: node-modules - -yarnPath: .yarn/releases/yarn-4.1.1.cjs +checksumBehavior: update + +nodeLinker: node-modules + +yarnPath: .yarn/releases/yarn-4.1.1.cjs diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000..b9ddec9500 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,10 @@ +FROM node:lts +WORKDIR /app + +COPY package.json yarn.lock ./ + +COPY . . + +EXPOSE 5086 + +CMD [ "yarn", "dev" ] diff --git a/Docs.csproj b/Docs.csproj deleted file mode 100644 index 0c1e95e16b..0000000000 --- a/Docs.csproj +++ /dev/null @@ -1,40 +0,0 @@ - - - - Exe - netcoreapp3.1 - $(MSBuildProjectDirectory) - $(DefaultItemExcludes);output\**;.gitignore - - - - - - - - - - - - - Never - - - Never - - - Never - - - Never - - - Never - - - - - - - - \ No newline at end of file diff --git a/Docs.sln b/Docs.sln deleted file mode 100644 index 2c71b3955f..0000000000 --- a/Docs.sln +++ /dev/null @@ -1,25 +0,0 @@ - -Microsoft Visual Studio Solution File, Format Version 12.00 -# Visual Studio Version 16 -VisualStudioVersion = 16.0.30011.22 -MinimumVisualStudioVersion = 10.0.40219.1 -Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Docs", "Docs.csproj", "{C337F609-A890-4E52-BDA3-91658039B0E3}" -EndProject -Global - GlobalSection(SolutionConfigurationPlatforms) = preSolution - Debug|Any CPU = Debug|Any CPU - Release|Any CPU = Release|Any CPU - EndGlobalSection - GlobalSection(ProjectConfigurationPlatforms) = postSolution - {C337F609-A890-4E52-BDA3-91658039B0E3}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {C337F609-A890-4E52-BDA3-91658039B0E3}.Debug|Any CPU.Build.0 = Debug|Any CPU - {C337F609-A890-4E52-BDA3-91658039B0E3}.Release|Any CPU.ActiveCfg = Release|Any CPU - {C337F609-A890-4E52-BDA3-91658039B0E3}.Release|Any CPU.Build.0 = Release|Any CPU - EndGlobalSection - GlobalSection(SolutionProperties) = preSolution - HideSolutionNode = FALSE - EndGlobalSection - GlobalSection(ExtensibilityGlobals) = postSolution - SolutionGuid = {2FB3922B-494A-45EB-A479-FC507B8E107C} - EndGlobalSection -EndGlobal diff --git a/Program.cs b/Program.cs deleted file mode 100644 index 11000437ae..0000000000 --- a/Program.cs +++ /dev/null @@ -1,37 +0,0 @@ -using System.Threading.Tasks; -using Docs.Shortcodes; -using Statiq.App; -using Statiq.Common; -using Statiq.Markdown; -using Statiq.Web; - -namespace Docs -{ - public static class Program - { - public static async Task Main(string[] args) => - await Bootstrapper.Factory - .CreateWeb(args) - .AddSetting(Keys.Host, "docs.chocolatey.org") - .AddSetting(Keys.LinksUseHttps, true) - .AddSetting(Constants.EditLink, ConfigureEditLink()) - .AddSetting(WebKeys.GatherHeadingsLevel, 5) - .ConfigureSite("chocolatey", "docs", "master") - .ConfigureTemplates(templates => ((RenderMarkdown)templates[MediaTypes.Markdown].Module).UseExtension(new Markdig.Extensions.Emoji.EmojiExtension())) - .AddShortcode("Children", typeof(ChildrenShortcode)) - .AddPipelines() - .RunAsync(); - - private static Config ConfigureEditLink() - { - return Config.FromDocument((doc, ctx) => - { - return string.Format("https://github.com/{0}/{1}/edit/{2}/input/{3}", - ctx.GetString(Constants.Site.Owner), - ctx.GetString(Constants.Site.Repository), - ctx.GetString(Constants.Site.Branch), - doc.Source.GetRelativeInputPath()); - }); - } - } -} diff --git a/README.md b/README.md index 5499999f4e..b4f010af50 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,115 @@ -# Chocolatey Docs - -This repository contains the source files for the documentation site that can be found here: - -https://docs.chocolatey.org/en-us/ - -This site is built using [Statiq](https://statiq.dev/). - -## Thanks - -The original template that was used to create this docs site came from the work that was done by [Patrik Svensson](https://github.com/patriksvensson), on his [Spectre.Console](https://spectresystems.github.io/spectre.console/) and [Spectre.Cli](https://spectresystems.github.io/spectre.cli/) docs sites. Huge thank you to Patrik for all his help! - -## Writing Documentation - -Listed below are some of the areas we consider important when writing. We have two goals: - -* **Consistency**. It's important when writing to be consistent in all areas including, but not limited to, headings, code style, formatting, use of bold and italics. We acknowledge that as our writing style has evolved not all of our writing has followed. When we write we should be consistent. -* **Clarity**. When writing we must remember to write for others and not just for ourselves. It's important to understand that jargon or acronyms can cause confusion, misunderstanding and a barrier for others who are not familiar with the terms. Avoid using jargon where you can and only use acronyms once they have been defined. Ensure any [jargon or acronyms used are documented](https://docs.chocolatey.org/en-us/information/jargon-buster). - -To help with these goals, please refer to our guides on [writing documentation](https://design.chocolatey.org/content-and-marketing/writing-documentation) and the use of [language and grammar](https://design.chocolatey.org/content-and-marketing/language-and-grammar). - -## Building the Site - -There are two options to build the site: - -1. Build it on your own computer. -1. Build it using a Docker container. - -### Build the Site On Your Computer - -There are a number or pre-requisites that are needed before you will be able to build the website locally. These include: - -* .NET Core SDK -* NodeJS - -There is a `.\setup.ps1` file in the root of this repository that can be used to install all necessary packages. - -#### Building the Site - -To build the site locally on your computer, either run the `.\build.ps1` or the `build.sh` file (depending on your operating system). This will compile the site, and all generated output file be placed into the `output` folder. - -### Build the Site Using a Docker Container - -There are two ways you can do this: - -* Using the Visual Studio Code Dev Containers extension. -* Running the Docker container from the command line. - -#### Using the Visual Studio Code Dev Containers Extension - -Connect to the Docker Container in Visual Studio Code. This will launch Visual Studio Code and open a terminal that is running inside the Docker Container whose configuration is defined in `/.devcontainer/devcontainer.json` and `/.devcontainer/Dockerfile`. You can now move onto [previewing the site](#previewing-the-site). - -#### Running the Docker Container From the Command Line - -Follow these steps: - -1. Run `docker pull mcr.microsoft.com/vscode/devcontainers/dotnet:0-3.1-focal`. -1. Change to the `/.devcontainer` directory and run `docker build . --tag chocolatey-docs-container`. This will build the image you can use to preview the docs. Note that you can change the name `chocolatey-docs-container` to whatever you want. - -#### Previewing the Site - -To preview the site locally on your computer, either run the `.\preview.ps1` or the `preview.sh` file (depending on your operating system). If you are previewing the site using the Docker container from the command line, change to the directory containing this repository and run `docker run -p 5080:5080 -v ${pwd}:/workspaces/chocolatey-docs -w /workspaces/chocolatey-docs -i -t chocolatey-docs-container /bin/bash ./preview.sh`. Replace `chocolatey-docs-container` with whatever you named your container above. - -Once completed, you should be able to open a browser on your machine to `http://localhost:5080` and the site will be loaded. Once running, any changes made to the files within the `input` folder will cause the site to be rebuilt with the new content. - -### Troubleshooting the build - -If you are having build errors with `'copyTheme' errored after`, try removing the `node_modules` directory and clearing your yarn cache with `yarn cache clean`. - -If you receive the error `The configured user limit (128) on the number of inotify instances has been reached, or the per-process limit on the number of open file descriptors has been reached` then you can increase the number by running `echo fs.inotify.max_user_instances=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`. See [this GitHub comment](https://github.com/dotnet/aspnetcore/issues/8449#issuecomment-512275929) for more information. - -## Adding a New Highlight - -To add a new Highlight, follow the steps below: - -1. Check to see if the Highlight you are writing already has a folder associated with it. This will match the current year and month that you are posting the Highlight in. If there is already a folder, copy the file from `/en-us/highlights/template/template.md` into the folder your new Highlight will go in, then skip to step #4. -1. Copy the folder `/en-us/highlights/template` and rename it to the format of "YYYY-MM". For example: "2023-04". -1. In your new folder, update the `index.md` file: - 1. Change the `PostedDateTime` to the first day of the current month. This should match the folder name. This will be the heading title that appears on the [Highlights page](xref:highlights). - 1. Remove the `IsActive: false` line completely. This is set to `true` by default, and a section will now appear for the given month on the Highlights page. -1. In your new folder, change the file name of `template.md` to match the title of the Highlight you are writing. This should be something that can easily be identified if changes will need to be made by another person later. -1. Update your new (previously `template.md`) file as needed: - 1. Remove the `IsActive: false` line completely. This is set to `true` by default, and will now be shown on the Highlights page. - 1. To make the Highlight appear on the Home page, remove the `ShowOnHome: false` line completely. This is set to `true` by default, and will now be shown on the Home page. - -## Build Status - -[![GitHub Actions Build Status](https://github.com/chocolatey/docs/workflows/Publish%20Documentation/badge.svg)](https://github.com/chocolatey/docs/actions?query=workflow%3A%22Build+Pull+Request%22) - -## Chat Room -Come join in the conversation about Chocolatey in our [Community Chat Room](https://ch0.co/community). - -Please make sure you've read over and agree with the [etiquette regarding communication](https://github.com/chocolatey/choco/blob/master/README.md#etiquette-regarding-communication). - -## Search - -Search uses [Algolia DocSearch](https://docsearch.algolia.com/) as backend. -Configuration for crawler is available at https://github.com/algolia/docsearch-configs/blob/master/configs/chocolatey.json. \ No newline at end of file +# Chocolatey Docs + +This repository contains the source files for the documentation site that can be found here: + +https://docs.chocolatey.org/en-us/ + +This site is built using [Astro](https://astro.build/). + +## Writing Documentation + +Listed below are some of the areas we consider important when writing. We have two goals: + +* **Consistency**. It's important when writing to be consistent in all areas including, but not limited to, headings, code style, formatting, use of bold and italics. We acknowledge that as our writing style has evolved not all of our writing has followed. When we write we should be consistent. +* **Clarity**. When writing we must remember to write for others and not just for ourselves. It's important to understand that jargon or acronyms can cause confusion, misunderstanding and a barrier for others who are not familiar with the terms. Avoid using jargon where you can and only use acronyms once they have been defined. Ensure any [jargon or acronyms used are documented](https://docs.chocolatey.org/en-us/information/jargon-buster). + +To help with these goals, please refer to our guides on [writing documentation](https://design.chocolatey.org/content-and-marketing/writing-documentation) and the use of [language and grammar](https://design.chocolatey.org/content-and-marketing/language-and-grammar). + +## Building the Site + +There are multiple options to build the site: + +1. Build it on [your own computer](#build-the-site-on-your-computer). +1. Open in [GitHub Codespaces](https://codespaces.new/chocolatey/docs?devcontainer_path=.devcontainer/devcontainer.json). +1. Build it using a [Dev Container](#build-the-site-using-a-dev-container). +1. Build it using [Docker](#build-the-site-using-docker). + +### Build the Site On Your Computer + +Ensure that you have Node v20+ installed by running `node -v`. There is a `.\setup.ps1` file in the root of this repository that uses Chocolatey to install or upgrade Node to the correct version. + +After confirming the required Node version, run the following command from a terminal: + +``` +yarn dev +``` + +This will compile the site, and bring up a preview on `http:localhost:5086`. Any changes you make will automatically be hot reloaded. + +### Build the Site Using a Dev Container + +Follow these steps to open the project in a [Dev Container](https://containers.dev/): + +1. Install the Dev Containers extension for Visual Studio Code if you haven't already. You can install it from the Extensions view (Ctrl+Shift+X) by searching for "Dev Containers". +2. Open the Command Palette (Ctrl+Shift+P or F1) and run the command `Dev Containers: Open Folder in Container...`. +3. Select the folder containing this repository (or the repository root if you've already opened it in VS Code). +4. Wait for the Dev Container to start up. This may take a few minutes the first time as it needs to download the container image. Subsequent starts will be faster. +5. Once the Dev Container is ready, you'll have a full development environment with all the required tools and dependencies pre-installed. Any changes you make will automatically be hot reloaded. +6. When you're done, you can close the Dev Container by running the `Dev Containers: Close Remote Connection` command from the Command Palette. + +### Build the Site Using Docker + +From a terminal, run the following: + +``` +docker build -t chocolatey-docs-container . +``` + +Once this is complete, run the following from the same terminal: + +``` +docker run -p 5086:5086 -v $(pwd):/app chocolatey-docs-container +``` + +This will compile the site, and bring up a preview on `http:localhost:5086`. Any changes you make will automatically be hot reloaded. + +### Troubleshooting the build + +If you are having build errors with `'copyTheme' errored after`, try removing the `node_modules` directory and clearing your yarn cache with `yarn cache clean`. + +If you receive the error `The configured user limit (128) on the number of inotify instances has been reached, or the per-process limit on the number of open file descriptors has been reached` then you can increase the number by running `echo fs.inotify.max_user_instances=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`. See [this GitHub comment](https://github.com/dotnet/aspnetcore/issues/8449#issuecomment-512275929) for more information. + +## Understanding Astro + +The [Chocolatey Design System](https://design.chocolatey.org) and [choco-astro](https://github.com/chocolatey/choco-astro) contain information on how to understand several Astro concepts: + +* Learn how to [override automatically generated heading ID's](https://github.com/chocolatey/choco-astro?tab=readme-ov-file#overriding-automatically-generated-heading-ids). +* Learn about Astro and how to use [Components in `.mdx` and `.astro`](https://design.chocolatey.org/foundations/astro) file types. +* Learn how to use the [`` Component](https://design.chocolatey.org/components/callouts) to display notes and important information. +* Learn how to use the [`` Component](https://design.chocolatey.org/collapse-button) to display a button that triggers a collapsed element. +* Learn how to use the [` - - -## 1.0.0 (March 21, 2022) - -> :choco-warning: **WARNING** -> -> The dependencies of the chocolatey-agent package have changed in this release. It now requires Chocolatey Licensed Extension v4.0.0. - -### Breaking Change - -- Update Chocolatey Licensed Extension dependency to v4.0.0. - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.13.0 (February 28, 2022) - -> :choco-warning: **WARNING** -> -> The dependencies of the chocolatey-agent package have changed in this release, and it now requires Chocolatey Licensed Extension v3.2.0+. - -### Breaking Changes - -- Chocolatey Central Management - Enhanced communication method for reporting information in Chocolatey Central Management. - - **NOTE:** This version of Chocolatey Agent is backwards compatible with versions of Chocolatey Central Management earlier than 0.8.0. However, we always recommend updating to the latest version of Chocolatey Central Management. - -### Improvements - -- Chocolatey Central Management - - Add logic to retry reporting of a Deployment Step result to Chocolatey Central Management if it initially fails. - - Ensure that no expanded sensitive variables are captured in log that is returned to Chocolatey Central Management. - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.12.1 (September 14, 2021) - -### Bug Fix - -- [Security] Fix - Deployments - Sensitive arguments are included in log file when advanced Deployment Steps are executed via Chocolatey Central Management - see [licensed #255](https://github.com/chocolatey/chocolatey-licensed-issues/issues/255). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.12.0 (September 2, 2021) - -> :choco-warning: **WARNING** -> -> The dependencies of the chocolatey-agent package have changed in this release, and it now requires chocolatey.extension v2.2.0. - -### Bug Fixes - -- Central Management - - Fix - Second and subsequent Deployment Steps to Chocolatey Agent with PowerShell v4 come back inconclusive (possibly earlier PowerShell versions as well) - see [licensed #237](https://github.com/chocolatey/chocolatey-licensed-issues/issues/237). - - Fix - Deployments - Log does not contain all information under error circumstances. - -### Improvements - -- [Security] XML External Entity attack in log4net (CVE-2018-1285) - see [licensed #253](https://github.com/chocolatey/chocolatey-licensed-issues/issues/253). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.11.2 (November 5, 2020) - -### Bug Fix - -- Fix - Deployments - An execution timeout in seconds value of `0` for a Deployment Step is not treated as infinite. - -### Improvements - -- Provide clarity in log messages when salt additive configuration values are misconfigured. - -## 0.11.1 (October 5, 2020) - -### Bug Fix - -- Fix - CCM - Prevent incorrect exit code of -1 from successful PowerShell script Deployment Step when no exit code is explicitly supplied by the script. - -## 0.11.0 (June 25, 2020) - -### Breaking Changes - -- Chocolatey Agent v0.11.0 will only work with Central Management v0.3.0+. Upgrade order doesn't matter as you'll need to be on CCM v0.3.0 and Agent v0.11.0 before things start working again. See https://docs.chocolatey.org/en-us/central-management/#ccm-component-compatibility-matrix. - -### Bug Fixes - -- Fix - CCM - passphrases do not match on check-in (report_computer_information) - see [Licensed #152](https://github.com/chocolatey/chocolatey-licensed-issues/issues/152). -- Fix - CCM Deployments - Deployments agent exit code of -1 reports successful Deployment Step - see [Licensed #153](https://github.com/chocolatey/chocolatey-licensed-issues/issues/153). - -## 0.10.0 (June 18, 2020) - -### Breaking Changes - -- Chocolatey Agent v0.10.0 will only work with Central Management v0.2.0+. Please upgrade Central Management first if you are using CCM with the agent service. - -> :choco-info: **NOTE** -> -> Log locations have changed. Please see [Log File for Chocolatey Agent](xref:setup-agent#log-file-location-for-chocolatey-agent) for more information. - -### Features - -- Execution for Chocolatey Central Management Deployments. - -### Bug Fixes - -- Fix - Monitoring `chocolatey.config` for changes could potentially lock the file from being written to by Chocolatey CLI. -- Fix - Logging - the service stops responding to calls and stops logging after choco configuration file is edited. -- Fix - CCM Reporting - Do not report unfound packages as outdated. - -### Improvements - -- Logging - Log to the root logs folder of Chocolatey installation. - -## 0.9.3 (March 26, 2020) - -### Bug Fixes - -- Central Management Reporting: - - Fix - Ensure best available TLS is used - see [Licensed #132](https://github.com/chocolatey/chocolatey-licensed-issues/issues/132). - -## 0.9.2 (January 30, 2020) - -### Improvements - -- When reporting into CCM, add the URL that is being used in log to aid when debugging issues. - -## 0.9.1 (April 30, 2019) - -### Bug Fixes - -- Self-Service / Background Mode: - - Fix - Multiple quoted options being parsed incorrectly - see [Licensed #78](https://github.com/chocolatey/chocolatey-licensed-issues/issues/78). - -## 0.9.0 (March 18, 2019) - -### Features - -- Chocolatey Central Management Reporting - Clients can now report into Chocolatey Central Management on a configurable basis. For more information, please see [the documentation](https://docs.chocolatey.org/en-us/features/chocolatey-central-management). - -### Bug Fixes - -- Self-Service / Background Mode: - - Fix - Package Arguments not being passed from Chocolatey Agent to Chocolatey CLI properly - see [Licensed #60](https://github.com/chocolatey/chocolatey-licensed-issues/issues/60). - - Fix - Chocolatey Agent does not pass the exit code back to the console (service side) - see [Licensed #51](https://github.com/chocolatey/chocolatey-licensed-issues/issues/51). - - Fix - Execution times out after 10 minutes - ignores configuration - see [Licensed #41](https://github.com/chocolatey/chocolatey-licensed-issues/issues/41). - -## 0.8.1 (September 28, 2017) - -### Bug Fixes - -- Fix - bump dependency on Chocolatey Licensed Extension to ensure user is created with complex password instead of created with no password and then updated with complex password. - -## 0.8.0 (September 27, 2017) - -### Breaking Changes - -- [Security] Use 'ChocolateyLocalAdmin' user and manage the user by default - using LocalSystem doesn't work well with all software installations. Using a local user that is an admin works much better for ensuring applications are installed. If you need the previous functionality, pass `/UseDefaultChocolateyConfigUser`. This will use whatever Chocolatey is configured to use by default for new service installations. You can also pass in a username and optionally a password for a domain account or local administrator account. - -### Improvements - -- Upgrade - Pass `/NoRestartService` to upgrade the service without shutting down the current running service. You will need to restart the service to take advantage of the new changes - see [#26](https://github.com/chocolatey/chocolatey-licensed-issues/issues/26). -- Install/Upgrade - Pick username/password for runtime. Pass `/Username:value /Password:value2` through package parameters. -- Install/Upgrade - Pass `/EnterPassword` through package parameters to have Chocolatey ask for the user password at runtime during installation. Captures as a secure string. - -## 0.7.0 (June 27, 2017) - -### Breaking Changes - -- Fix - Use a URI with WCF named pipes that doesn't exclusively hold a lock on the root (blocking other services) - see [#12](https://github.com/chocolatey/chocolatey-licensed-issues/issues/12). - -### Bug Fixes - -- Fix - Allow chocolatey.lib (not just calls from choco.exe) to run self-service. - -## 0.6.0 (March 20, 2017) - -### Breaking Changes - -- Sources must be opted in for self-service if the feature `UseBackgroundServiceWithSelfServiceSourcesOnly` is turned on. This is automatically the case with Chocolatey Licensed v1.10.0+ (and Chocolatey 0.10.4+). - -### Bug Fixes - -- Fix - Sources using nupkg/nuspec were being allowed. This is now disabled as well. - -## 0.5.0 (January 14, 2017) - -### Breaking Changes - -- New pattern for dependencies requires a reload of the interface that works between the Agent and Chocolatey.Extension, requiring a bump in the sub v1. - -## 0.4.0 (January 4, 2017) - -Initial Release - -### Features - -- Streams logging messages back to the caller in realtime. -- Audits disallowed calls / attempted abuses of the service. -- Only runs Chocolatey functions. -- Ensures installation from approved sources only. -- Receives and passes user context to Chocolatey functions. -- Works exclusively with Chocolatey for Business - checks passcode prior to running command. -- Processes one command at a time with locking algorithm. diff --git a/input/en-us/agent/setup.md b/input/en-us/agent/setup.md deleted file mode 100644 index 5a2e794290..0000000000 --- a/input/en-us/agent/setup.md +++ /dev/null @@ -1,410 +0,0 @@ ---- -Order: 20 -xref: setup-agent -Title: Setup -Description: Information on how to setup Chocolatey Agent ---- - -To install the Chocolatey Agent service, you need to install the `chocolatey-agent` package. The Chocolatey Agent is only available for business edition customers to install from the licensed source (customers trialling the business edition will be provided instructions on how to install). - -## Requirements - -* Chocolatey (`chocolatey` package) -* Chocolatey for Business (C4B) Edition -* Chocolatey Licensed Extension (`chocolatey.extension` package) -* Chocolatey Agent Service (`chocolatey-agent` package) - -> :choco-info: **NOTE** -> -> The Chocolatey Agent Service requires Log On As Service and Log On As Batch rights. We attempt to set these rights on the user at the time of installation via Local Policy, but if you have a restrictive Group Policy that will be applied to the system, please ensure that the user account you are attempting to use (or ChocolateyLocalAdmin as the default) has the correct permissions applied in your Group Policy. - -## Chocolatey Agent Install Options - -Starting with Chocolatey Agent v0.8.0+, the service will install as a local administrative user `ChocolateyLocalAdmin` by default (and manage the password as well). However you can specify your own user with package parameters (or have it use `LocalSystem`). Using a local administrator account allows for more things to be installed without issues. It also will allow easier shortcuts and other items to be put back on the correct user (the original requestor). You can specify a domain account as well. Prior to `v0.8.0`, Chocolatey Agent would install as LocalSystem (`SYSTEM`) and would require additional customization. - -> :choco-warning: **WARNING** -> -> Chocolatey Agent should **not** be installed on a machine that is acting as a domain controller. Doing so is not a supported configuration. Domain controllers do not have local accounts other than the LocalSystem (`SYSTEM`) account. Any other local administrator account, such as the default `ChocolateyLocalAdmin` account, used to install Chocolatey Agent on a domain controller will by default become a domain administrator account. - -> :choco-info: **NOTE** -> -> If you are using file shares for sources, you may want to ensure the account or computer has network access permissions for the file share(s). - -## Package Parameters - -Note items with "`:`" mean a value should be provided, items without are simply switches. - -* `/Username:` - provide username - instead of using the default 'ChocolateyLocalAdmin' user. This user will need to be a member of local administrators due to the privileges needed for this service - this is typically ensured during installation. `Logon as Service` and `Logon as Batch` privileges are also ensured. -* `/Password:` - optional password for the user. -* `/EnterPassword` - receive the password at runtime as a secure string -* `/UseDefaultChocolateyConfigUser` - use the default username from Chocolatey's configuration. This may be LocalSystem. -* `/NoRestartService` - do not shut down and restart the service. You will need to restart later to take advantage of new service information. - -## Chocolatey Managed Password - -When Chocolatey manages the password for a local administrator, it creates a very complex password: - -* It is 32 characters long. -* It uses uppercase, lowercase, numbers, and symbols to meet very stringent complexity requirements. -* The password is different for every machine. -* Due to the way that it is generated, it is completely unguessable. -* No one at Chocolatey Software could even tell you what the password is for a particular machine without local access. - -See [FAQ](#faq) below for more discussion on security aspects. - -### Chocolatey Agent Service Windows Account Considerations - -* Windows Account (required, defaults to `ChocolateyLocalAdmin`) - * The Chocolatey Agent Service requires **an** administrative account, whether that is a domain account or a local account - it just needs to be a local admin (a member of the Administrators group). - * The agent service doesn't specifically require the `ChocolateyLocalAdmin` account, any Windows account can be used. The `ChocolateyLocalAdmin` is used as the default if one is not specified. - * Upon use of an account during installation, it will make that account a member of the Administrators account. - * The account used will also be granted LogonAsService and LogonAsBatch privileges. -* Managed Password (optional, default) - * When the `ChocolateyLocalAdmin` account is used, it generates a managed password that is different on every machine, 32 characters long, meets complexity requirements, and basically very strong. - * To determine the managed password, it would take access to the box and someone from Chocolatey Software who has access to the algorithm used to generate the password (more information in the FAQs below). -* Rotating/Updating Passwords - * If a different account with a rotating password is used, the service will need to be updated with the new credentials and restarted soon after changing that password. - * The managed password is not currently updated/rotated, but it is something we are looking at how best to implement. - -## Self-Service Anywhere Setup - -See [Background Mode Setup](#background-mode-setup). - -## Background Mode Setup - -To set Chocolatey in background mode, you need to run the following: - -* `choco upgrade chocolatey-agent ` (see [agent install options](#chocolatey-agent-install-options)) -* `choco feature disable --name="'showNonElevatedWarnings'"` -* `choco feature enable --name="'useBackgroundService'"` -* You also need to opt in sources in for self-service packages. See [choco source](xref:choco-command-source) (and `--allow-self-service`). You can also run `choco source -?` to get the help menu. - * OPTIONAL (not recommended): Alternatively, you can allow any configured source to be used for self-service by running the following: `choco feature disable --name="'useBackgroundServiceWithSelfServiceSourcesOnly'"` . We do not recommend this as it could be a security finding if you shut it off. -* OPTIONAL (highly recommended): If you want self-service to apply only to non-administrators, run `choco feature enable --name="'useBackgroundServiceWithNonAdministratorsOnly'"` (requires Chocolatey Extension v1.11.1+). Do understand this means that a real non-administrator, not an administrator in a non-elevated UAC context (that scenario will go the normal route and will not go through background mode). -* OPTIONAL (varied recommendations): If you want to configure custom commands (not just install/upgrade), use something like `choco config set --name backgroundServiceAllowedCommands --value "install,upgrade,pin,sync"` (with the commands you want to allow, requires Chocolatey Extension v1.12.4+). See [commands consideration](#command-customization-consideration) below. -* OPTIONAL (highly recommended): If you want to allow non-admins to uninstall packages, you can also restrict down to only the packages they have installed/upgraded. Run `choco feature enable --name="'allowBackgroundServiceUninstallsFromUserInstallsOnly'"` (requires Chocolatey Extension v2.0+). -* OPTIONAL (highly recommended): For use with Chocolatey GUI, you need Chocolatey Extension v1.12.4+, and at least Chocolatey GUI v0.15.0. **Uninstall any version of the GUI you already have installed first**, then run `choco upgrade chocolateygui -y --allow-downgrade` (you will also need at least .NET 4.5.2 installed) -* DOES NOT WORK WITH UAC, DO NOT USE UNTIL [FIX IS ANNOUNCED](https://groups.google.com/group/chocolatey-announce)! OPTIONAL (recommended if you use installers that are not completely silent): If you want self-service to interactively manage installations, run `choco feature enable --name="'useBackgroundServiceInteractively'"` (requires Chocolatey Extension v1.12.10+). This requires that you use the `ChocolateyLocalAdmin` account with the Chocolatey-managed password as passwords are not stored and the service would need to produce that at runtime. There are some security considerations and why this is not turned on by default. Please see [interactive self-service consideration](#interactive-self-service-consideration). - -> :choco-info: **NOTE** -> -> Once you are all setup, please review the [Common Errors and Resolutions](#common-errors-and-resolutions) section so you will be familiar if you run into any issues with working with sources. - -An example script: - -This carries our typical recommendations, but you could adjust from above. - -```powershell -choco upgrade chocolatey-agent -y -choco feature disable --name="'showNonElevatedWarnings'" -choco feature enable --name="'useBackgroundService'" -choco feature enable --name="'useBackgroundServiceWithNonAdministratorsOnly'" -# allow uninstalls as well: -#choco config set --name backgroundServiceAllowedCommands --value "install,upgrade,uninstall" -# restrict uninstalls to just packages the user has installed/upgraded (requires Chocolatey Extension v2.0+): -#choco feature enable --name="'allowBackgroundServiceUninstallsFromUserInstallsOnly'" - -# TODO: opt in your sources with --allow-self-service - run choco source -? for details -``` - -> Best practices in scripts are noted here: -> * Use `upgrade` instead of `install` - upgrade is more making the script reusable when newer versions are available. -> * Always use `-y` to ensure nothing stops and prompts for more than 30 seconds. -> * When using options prefer a longer name (`--name` versus the short `-n`) to make the scripts more self-documenting -> * When using options that have a value passed, add an `=` between and surround the value with `"''"` (`--name="'value'"`). This ensures that the argument is not split between different versions/editions of Chocolatey. This also ensures that values like `.` and `\\` are not escaped by PowerShell. - -### Command Customization Consideration - -Starting with Chocolatey Licensed Extension v1.12.4, you are allowed to configure what commands can be routed through the background service. Please note that Chocolatey Licensed defaults to `install` and `upgrade` as that is the most secure experience. However you can add uninstall and some other commands as well. Uninstall does have some security considerations as it would allow a non-administrator to remove software that you may have installed, including the background service itself. - -**Available Commands**: - -* info - do not add if you want sources hidden from non-admins -* list/search - do not add if you want sources hidden from non-admins -* outdated - do not add if you want sources hidden from non-admins -* install - default -* upgrade - default -* uninstall - keep in mind there may be security implications for this -* optimize -* pin -* sync -* download - Chocolatey Licensed Extension v1.12.12+ - keep in mind if you have shut off a non-admin's ability to run this they still won't be able to without also disabling the `adminOnlyExecutionForDownloadCommand` feature. - -**Blacklisted Commands**: - -* config -* feature -* source -* apikey - -Chocolatey does not allow for configuration changing commands to be routed through the background service as that would allow users to be able to change configuration and that could be detrimental. For instance, a user could add a local source with a package they've created that promotes themselves to an administrator (escalation of privilege). As that constitutes a security issue, we do not allow it. - -For the same reason, we do not recommend allowing sources you do not control to be allowed for self-service. - -### Interactive Self-Service Consideration - -When using the self-service with `useBackgroundServiceInteractively`, it is similar to "Run As". Microsoft used to allow Windows services to interact with the desktop but removed the functionality (of "Allow Service to Interact with the Desktop") in Windows Vista and limited all services into what is known as Session 0 isolation. In Session 0, those services can access a desktop, but not the interactive user's desktop (at least it is very, very difficult to do so). Microsoft did this as a security consideration as allowing a privileged account to run executables in a non-administrative user context opens the potential to allow a non-admin to gain privileges to a system (known as escalation of privilege). Depending on what is allowed for folks to install, as long as those package installations do not open a command shell and wait for user input, the potential is quite low. However it is something to keep in mind and assess before turning on this feature (and why it is off by default). - -However sometimes you work with installers that refuse to be silent. You might get them down to unattended (meaning they still have required input or window pop ups, but they are all handled and automatically closed), but they won't get to silent without a different option. Here are some options from most preferred to least preferred in getting those installers that are not fully silent to work: - -* (Silent) Find a portable version of the tool that doesn't run a badly behaved installer. Looked for a zipped up version, you can easily create a Chocolatey package from these. -* (Silent) Find an alternative that does the same thing, but has silent installers. It's a consideration, but maybe not something you can or are willing to explore. Moving on... -* (Silent) Use MSI repackaging to produce a completely silent installer. It works by recording everything that happens when you run the install and creates an MSI to do the same. This would need to be done for every version. There are tools out there that can do this, some of which are VERY expensive. -* (Unattended/Interactive) Use AutoHotKey or AutoIT (or some other tool) to automate the key presses and values being sent to the interfaces. This can be brittle, but can typically be quickly implemented. - -If you must run in the context of working with "unattended", non-silent installations, you need to take the above security consideration into account if you want to be able to manage those installations using the background service. - -## Chocolatey Central Management Agent Setup - -Please see [Central Management Client Setup](xref:ccm-client) for details. - -> :choco-info: **NOTE** -> -> This will also contain more FAQs and Common Errors and Resolutions related to communication with Central Management. - -## Log File Location For Chocolatey Agent - -The Chocolatey Agent log file is located at `$env:ChocolateyInstall\logs\chocolatey-agent.log`. If you are on a version of Chocolatey Agent prior to v0.10.0, the log will be located at `$env:ChocolateyInstall\lib\chocolatey-agent\tools\service\logs\chocolatey-agent.log`. - -## Chocolatey Agent Roadmap - -* Maintenance Windows: Admins will be able to schedule when upgrades occur. -* Toast Notifications: Let users know when things are happening, and let users know when upgrades are available for Self-Served applications -* ~~Self-Service: Admins will be able to configure what commands can be run through the background service.~~ Completed with Chocolatey Extension v1.12.4. -* Self-Service: Admins will have more granular control of what certain users can install. -* ~~Report into Central Management~~ - completed May 2019 -* ~~Handle tasks from Central Management Deployments~~ - completed June 2020 - -## FAQ - -### How do I take advantage of Chocolatey Agent? - -You must have a [Business edition of Chocolatey](https://chocolatey.org/compare). Business editions are great for organizations that need to manage the total software lifecycle. - -### I'm a licensed customer, now what? - -Once you have the agent service installed and Chocolatey for Business configured for background mode (see [Setup](#setup-1) above), most tools that use Chocolatey will automatically use the background service. - -### Will this become available for lower editions of Chocolatey? - -The background service and Central Management UI Console will only be available in C4B (Chocolatey for Business). - -### I have questions regarding Agent and Central Management - -Please see [Central Management Client Setup](xref:ccm-client) as the FAQs related to Central Management (CCM) are kept there. - -### I have Puppet or some other configuration management tool (RMM tool, infrastructure automation tool, etc.) that also runs Chocolatey. Can I configure it to skip background mode? - -Yes! Add `--run-actual` to your install options. Most likely your tool won't need to be reconfigured though as it will just work with background mode. You will need Chocolatey v0.10.3+ installed across your environment so Chocolatey handles the unknown arguments appropriately. - -Another (possibly better) way to handle this as of Chocolatey Extension v1.12.0, turn on the `useBackgroundServiceWithNonAdministratorsOnly` feature to make Self-Service apply only to non-administrators. See [Background Mode Setup](#background-mode-setup) for details. - -### How does it work? - -As a background service, it is able to call Chocolatey with an administrative account that is configured by you. It is secure communication that only starts once Chocolatey is configured to work with the background service. - -### What's the minimum Chocolatey licensed extension version that I need to install the agent? - -You need `chocolatey.extension` version 1.8.4+. - -### How is it secure? - -For Background Mode / Self-Service Installer: - -* Commands are ignored unless they come from the business edition of Chocolatey. -* Chocolatey installs can only be done from approved, configured sources. -* The background service validates commands prior to running. -* Attempted abuses of the service are logged for further review by an administrator later. - -For the Central Management UI / Console: - -* Coming later when central console is more complete. -* Communication will be done over TLS (w/self-signed certificate) or another medium with message encryption - -### Do you have an example of a message that goes across the agent service named pipe, from the client? - -The message is a serialized object that contains: - -* hashed passcode - SHA512 Hash of args, user, current directory, and a salt value only shared with agent and licensed edition -* command arguments to run - verified against validation checks -* username - this is what we'll use to ensure things like desktop shortcuts, etc -* timeout - how long before the command should timeout (from choco config) -* working directory - where is the context of this being executed, in case there are things to place relative to current directory - -Here is the interface: - -`void run_choco_command(string passcode, IEnumerable arguments, string userName, int timeout, string workingDirectory);` - -Keep in mind this message is only put on localhost. It does not go over any networks. - -### What is the purpose of the hash that is used to protect the named pipe? - -You may notice the hash changes every time based on what command is called. This is a security measure to ensure the call is coming from a configured Chocolatey client and not from another source. The agent will ignore anything that does not match up. - -### Does the agent service or Chocolatey stop installation from unconfigured sources? - -The agent stops unconfigured sources from installation. Right now it simply logs those abuses to the log file (that is locked down to admins for modify). The log file can be slurped into a tool like Splunk. Alternatively considering this is preview and we are waiting for feedback, we can look to providing those alerts in a different way, like the event log. We welcome any feedback on how you might like to see this. - -Chocolatey doesn't stop unconfigured sources for install, it lets the agent do so. Once Chocolatey is in background mode, all commands for install/upgrade go through the agent service. - -The one exception is when someone calls `--run-actual` in their arguments. But there is no escalation of privilege here because they would be running that under their own user context and thus only have the permissions granted to them already. - -### We want to set up the chocolatey agent service to use a domain account that will have local admin on each box. Can we do this? - -Yes, absolutely. You will pass those credentials through at install/upgrade time, and you will also want to turn on the feature `useRememberedArgumentsForUpgrades` (see [configuration](xref:configuration#features)) so that future upgrades will have that information available. The remembered arguments are stored encrypted on the box (that encryption is reversible so you may opt to pass that information each time). - -* `/Username:` - provide username - instead of using the default 'ChocolateyLocalAdmin' user. This user will need to be a member of local administrators due to the privileges needed for this service. -* `/Password:` - optional password for the user. -* `/EnterPassword` - receive the password at runtime as a secure string - -You would pass something like `choco install chocolatey-agent -y --params="'/Username:domain\account /EnterPassword'"` to securely pass the password at runtime. You could also run `choco install chocolatey-agent -y --params="'/Username:'" --package-parameters-sensitive="'/Password:'"` (or do it as part of `choco upgrade`). - -With Puppet, this could look something like: - -```puppet -package {'chocolatey-agent': - ensure => latest, - install_options => ['-pre','--params="',"'/Username:'", '"','--package-parameters-sensitive="', "'/Password:'", '"'], - require => Chocolateyfeature['useLocalSystemForServiceInstalls'], -} -``` - -where `` and `` could be pulled from Hiera or somewhere else. If you have access to the Puppet secrets type, then you can use that here as well. - -### Is the password stored anywhere? - -No, that would reduce the security of the password. It exists in memory long enough to set the value on user and the service and then it is cleared. - -There is no storage of the password anywhere other than how Windows stores passwords. - -### We are going to use our own account with a rotating password. When we rotate the password for the account that we use for the Chocolatey Agent, what do we need to do? - -Like with any service that uses rotating passwords, you will need to redeploy the service or go into the services management console and update the password. As it is much faster to deploy out that update, you can do something like `choco upgrade chocolatey-agent -y --params="'/Username:domain\account'" --package-parameters-sensitive="'/Password:newpassword'" --force` (the `--force` ensures the code is redeployed). - -### Tell me more about the Chocolatey managed password. - -So you've seen from above that - -* It is 32 characters long. -* It uses uppercase, lowercase, numbers, and symbols to meet very stringent complexity requirements. -* The password is different for every machine. -* Due to the way that it is generated, it is completely unguessable. -* No one at Chocolatey Software could even tell you what the password is for a particular machine without local access. - -Chocolatey uses something unique about each system, along with an encrypted value in the licensed code base to generate base password, then it makes some other changes to ensure that the password meets complexity requirements. We won't give you the full algorithm of how the password is generated as knowing the algorithm would be a security issue - like having a partial picture of a key, you could start working on how to break in. Unlike a picture of a key, even knowing the full algorithm doesn't get you everything you need as you would need local access to each box to determine the password for **each** machine. - -### Is the managed password stored or logged anywhere? - -No, that would reduce the security of the password. It exists in memory long enough to set the value on user and the service and then it is cleared. - -There is no storage of the password anywhere other than how Windows stores passwords. - -### Is the managed password the same on every machine? - -No, it is different for every machine it is deployed to. - -### How would someone potentially get access to the managed password? - -The Chocolatey licensed code base is encrypted, so only people that work at Chocolatey Software would be able to determine the password for a particular box (just that one) **IF** they have local access to that box. Even with all of the information and the algorithm, it's still going to take our folks a while to determine the password. That gets them access to one machine. Of course, Chocolatey folks are not going to do this for obvious reasons. - -So let's realize this to its full potential - If someone were able to hack the Chocolatey licensed codebase, they would be able to determine the full password algorithm. Then they'd also need to hack into your infrastructure and get local access to every box that they wanted to get the Chocolatey-managed password so they could get admin access to just that box. Taking this out a bit further, it's reasonable to assume that if someone has hacked into your infrastructure, it's highly unlikely they are going to be using a non-administrator account to get local access to a box so they can get the password for an administrator account for just that one box. It's more likely they would would already have a local admin account for the boxes they are attacking, and are likely to seek other attack vectors that are much less sophisticated. - -### Do you rotate the managed password on a schedule? - -We are looking to do this in a future release. We may make the schedule configurable. - -### Can I take advantage of Chocolatey managed passwords with my own Windows services? - -Yes, absolutely. If you use C4B's PowerShell Windows Services code, you will be able to install services and have Chocolatey manage the password for those as well. - -### Can I save an image with the agent already installed that I can deploy new machines from? - -Yes, however you need to keep in mind that there is a unique machine Id that will need to be erased so it can be regenerated. - -Make sure to include the following in your provisioning script to deploy the new images: - -```powershell -Write-Host "Removing Chocolatey Unique Machine GUID" -Remove-ItemProperty -Path "HKLM:\Software\Chocolatey" -Name "UniqueId" -Force -# Restart the Agent Service if it is running -``` - -Once you've removed this, you'll need to restart the Agent Service to get it regenerated. - -### Can we use an account for the service that is not a local administrator? - -Unfortunately no. The user account for the service must be a member of local administrators due to the privileges needed for this service. Typically the installation scripts will ensure the user becomes an administrator if they are not. - -### What is Run Actual? - -You may have seen `--run-actual`, what is that? - -This is a switch that is passed to opt out of Chocolatey Self-Service. It's typically passed by the agent service back to choco to run a command for a user. You typically would not issue this, but the agent service will, so you are likely to see it in the logs if you are looking closely. - -### Where is the agent service installed? - -The installation folder for `chocolatey-agent` is at `$env:ChocolateyInstall\lib\chocolatey-agent\tools\service`. - -## Common Errors and Resolutions - -### I have issues regarding Central Management - -Please see [Central Management Client Setup](xref:ccm-client) as the common errors and resolutions related to Central Management (CCM) are kept there. - -### Installs from custom source locations are not allowed in background mode. Please remove custom source and try again using default (configured) package source locations. - -You can not pass custom source arguments to Chocolatey, it will error. You need to set up sources in the Chocolatey configuration and any that are marked as allowed for self-service will be passed by the background service. - -> :choco-info: **NOTE** -> -> If you have run `choco feature disable --name useBackgroundServiceWithSelfServiceSourcesOnly`, then all configured sources will be passed by the background service. - -### I'm getting the following: "There are no sources enabled for packages and none were passed as arguments." - -This means you need to opt a source into self-service (new in Chocolatey Extension v1.10). - -This just involves ensuring a source is set so that it allows self-service. To do this you run `choco source add --name name --source location <--other details need repeated> --allow-self-service`. Editing a source happens when the name is the same in `choco source add`. - -To change this behavior back to the way it was previously, simply run `choco disable --name useBackgroundServiceWithSelfServiceSourcesOnly`. For feature options, run `choco feature list` or see [Self-Service Feature Configuration](xref:configuration#self-service-background-mode) - -### I'm having trouble seeing packages on a file share source - -Starting with Chocolatey Agent v0.8.0+, the service will default an install to a local administrative user `ChocolateyLocalAdmin`, but before that it installed as LocalSystem by default. These accounts may not have network access to UNC shares. We recommend changing the service to a named account that is a local admin that would also have network access (or setting machines into an active directory group and explicitly giving that group read permissions to the share and ACL). To specify your own user, you can do that at install time with [package parameters](#chocolatey-agent-install-options), or you can do that in the Service Manager properties for the service itself (future upgrades would need you to pass that user/pass at least the first time). - -So if you've set up a source like `choco source add -n="'name'" -s="'\\unc\packages'" --priority=1`, by default this may not work with the Chocolatey Agent. You would need to grant access to machines or anonymous access to the share (Everyone Read is likely not enough). - -A great read on your options can be found at the following Stack Exchange links: - -* https://serverfault.com/q/135867/79259 -* https://serverfault.com/q/41130/79259 - -A way to do this with LocalSystem: - -1. Create a global group on the Domain - * add all machines to this group -1. Add this group to the share permissions with "Read" Access -1. Add this group to the NTFS permissions with "Read" Access - -> :choco-info: **NOTE** -> -> You'll need to add this group itself and not nest it inside of another one. - -### The agent service is not picking up the new license - -Currently, you do need to restart agents. Here's a handy script: - -```powershell -Get-Service chocolatey-* | Stop-Service -Get-Service chocolatey-* | Start-Service -``` - -### Background Service is not being used for my non-administrator accounts - -If a user is a member of the Built-in AD group `Network Configuration Operators`, then that means they have an elevation token available and will be treated in the same way as administrative accounts. To fix this, you have two options: - -* Remove the users from `Network Configuration Operators` - PowerShell offers an alternative to `ipconfig /flushdns` that does not require admin permissions - `Clear-DnsClientCache`. -* OR `choco feature disable --name="'useBackgroundServiceWithNonAdministratorsOnly'"` - -Similar to the above, if a user is a member of the local `Power Users` group, then that means they have an elevation token available and will be treated in the same way as administrative accounts. To fix this, you have two options: - -* Remove the users from `Power Users` -* Force all users through the Background Service: `choco feature disable --name="'useBackgroundServiceWithNonAdministratorsOnly'"` \ No newline at end of file diff --git a/input/en-us/agent/upgrade.md b/input/en-us/agent/upgrade.md deleted file mode 100644 index dcaaba8efa..0000000000 --- a/input/en-us/agent/upgrade.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -Order: 30 -xref: upgrade-agent -Title: Upgrade -Description: Information on how to upgrade Chocolatey Agent ---- - -## Upgrade Process - -> :choco-info: **NOTE** -> -> The upgrade of `chocolatey-agent` through `chocolatey-agent` will require a restart of the service in order for the new version to be picked up. - -### Minor / Patch Versions (for example 1.1.x to 1.3.x, or 1.1.1 to 1.1.5) - -To upgrade Chocolatey Agent directly, you can upgrade it through Chocolatey CLI with the command `choco upgrade chocolatey-agent`. - -### Major Versions - -When upgrading Chocolatey Agent to a new major version (for example, **v1.x** to **v2.x**) a specific upgrade process needs to be followed to ensure that all its dependencies will be correctly installed. - -As an example, the upgrade process for v1.x to v2.x is as follows: - -1. Ensure you are on the latest stable **v1.x** version of Chocolatey CLI, **v5.x** version of Chocolatey Licensed Extension, and **v1.x** version of Chocolatey Agent. - - To find the latest versions, you can use `choco search --exact chocolatey --all-versions` (or `chocolatey.extension` / `chocolatey.agent` for those packages). - You can also visit [Chocolatey CLI's Chocolatey Community Repository page](https://community.chocolatey.org/packages/chocolatey) (or other packages' pages on the site) and look at the Version History section to get this list. -1. Upgrade `chocolatey` **first**. -1. Due to the dependency version ranges and Chocolatey CLI's dependency resolution, `chocolatey-agent` will be upgraded alongside the `chocolatey` package and associated dependencies. - -### Using Chocolatey Central Management to Upgrade chocolatey-agent - -Because Chocolatey Central Management uses `chocolatey-agent` to perform its actions, the upgrade will require a restart of the service. -The easiest way to do this is with a scheduled task as part of an Advanced Deployment Step. - -A recommended Advanced Deployment Step script to do this is as follows: - -> :choco-warning: **WARNING** -> -> If upgrading `chocolatey-agent` to a new **major** version, target **only** the `chocolatey` package for the `choco upgrade` command in the script below, instead of the `chocolatey-agent` package. - -```powershell -$delayInMinutes = 1 - -# If using an internal repository to install Chocolatey Agent, replace `chocolatey.licensed` below -# with the name or URL of your internally configured source. -choco upgrade chocolatey-agent --source 'chocolatey.licensed' - -# Ensure the deployment task registers as failed if the installation failed, and skip registering the -# scheduled task. -if ($LASTEXITCODE -ne 0) { - Write-Error 'The upgrade failed!' - exit $LASTEXITCODE -} - -# Restart the Agent service after the preset delay time via a scheduled task. -$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes($delayInMinutes) -$action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument "-WindowStyle Hidden -Command Restart-Service chocolatey-agent" -$principal = New-ScheduledTaskPrincipal -GroupId Administrators -RunLevel Highest -$settings = New-ScheduledTaskSettingsSet -Hidden -Register-ScheduledTask -Action $action -Trigger $trigger -TaskName "restart chocolatey-agent" -Description "Upgrade Chocolatey Agent" -Principal $principal -Settings $settings -Verbose:$false -``` - -> :choco-warning: **WARNING** -> -> Although the `ScheduledTasks` module is available on Windows Server 2012 R2, the [`chocolatey-agent` service encounters an error when trying to import it](https://github.com/chocolatey/chocolatey-licensed-issues/issues/273). It is recommended to explore other options for the scheduled task if you're using Windows Server 2012 R2. - -## Change Service Account Username or Password - -If you need to change the username or password of the Chocolatey Agent, you have a few options: - -* Change it through the Windows Service Manager -* Change it during an upgrade by [passing the new username/password to the upgrade command](xref:setup-agent#package-parameters) -* Change it during an uninstall and reinstall while [passing the new username/password to the install command](xref:setup-agent#package-parameters). - -> :choco-warning: **WARNING** -> -> The service password cannot be changed through a Chocolatey upgrade command while the service is running. - -### Use Chocolatey Central Management to Change the Service Account Username or Password - -If you use Chocolatey Central Management, you won't be able to use a Deployment Step to uninstall the agent and then install the agent. This is because the agent cannot change the username/password while is it running. Instead, you can send a Deployment Step that creates a scheduled task to uninstall the agent, then install with the new parameters. - -> :choco-info: **NOTE** -> -> Due to limitations of Windows Task Scheduler, it is likely that your users will see the PowerShell window initially, but it should disappear once PowerShell has fully started. - -An example advanced Deployment Step script to do this is as follows: - -```powershell -$delayInMinutes = 1 -$newUsername = '' -$newPassword = '' - -$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes($delayInMinutes) -$action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument "-WindowStyle Hidden -Command choco uninstall chocolatey-agent -y ; choco install chocolatey-agent -y --params='/Username:$newUsername' --package-parameters-sensitive='/Password:$newPassword'" -$principal = New-ScheduledTaskPrincipal -GroupId Administrators -RunLevel Highest -$settings = New-ScheduledTaskSettingsSet -Hidden -Register-ScheduledTask -Action $action -Trigger $trigger -TaskName "Upgrade chocolatey-agent" -Description "Upgrade Chocolatey Agent" -Principal $principal -Settings $settings -Verbose:$false -``` - -> :choco-info: **NOTE** -> -> Be sure to use [Sensitive Variables](xref:ccm-administration-sensitive-variables) to ensure the username and password don't get added to the Chocolatey logs when using Chocolatey Central Management version 0.7.0 or newer. - -> :choco-warning: **WARNING** -> -> Although the `ScheduledTasks` module is available on Windows Server 2012 R2, the [`chocolatey-agent` service encounters an error when trying to import it](https://github.com/chocolatey/chocolatey-licensed-issues/issues/273). It is recommended to explore other options for the scheduled task if you're using Windows Server 2012 R2. diff --git a/input/en-us/c4b-environments/ansible/client-setup.md b/input/en-us/c4b-environments/ansible/client-setup.md deleted file mode 100644 index 93e3291774..0000000000 --- a/input/en-us/c4b-environments/ansible/client-setup.md +++ /dev/null @@ -1,584 +0,0 @@ ---- -Order: 42 -xref: c4b-ansible-client-setup -Title: Client Setup -Description: How to Setup a Client Machine to Use the Chocolatey for Business Ansible Environment ---- - -## Summary - -Once you have your Chocolatey for Business environment deployed, you'll need to get clients talking to it. -To do that, you'll need to do the following on the clients: - -1. Ensure the client machine can access the Chocolatey Central Management service on port 24020, and the Sonatype Nexus service on 8443 (by default). -1. **If your certificate is self-signed:** [Install the SSL/TLS certificate](xref:c4b-azure-client-setup#ssl-certificate). -1. [Install Chocolatey components and configure the client for Chocolatey for Business](xref:c4b-ansible-client-setup#client-setup) (C4B) deployments and management. - -## Client Setup - -You will need the following values ready when running this script: - -* `FQDN`: The fully qualified domain name used to access your environment. -* `ccm_client_salt`: This is the client-side salt additive. More information about this can be found in the [Config Settings](xref:ccm-client#config-settings) docs. The value will have been provided during the deployment of the Chocolatey for Business environment. -* `ccm_service_salt`: This is the service salt additive. More information about this can be found in the [Config Settings](xref:ccm-client#config-settings) docs. The value will have been provided during the deployment of the Chocolatey for Business environment. -* `nexus_password`: The password for the `chocouser` account which is used by the client to access your environments' Sonatype Nexus service. The value will have been provided during the deployment of the Chocolatey for Business environment. - -The values generated during the deployment are available in the `CCM.html` file provided in the `credentials` directory within the deployment repository. - - - -::::{.tab-content .text-bg-body-secondary .p-3 .mb-3 .border-start .border-end .border-bottom .rounded-bottom} -:::{.tab-pane .fade .show .active #scenario-one role=tabpanel aria-labelledby=scenario-one-tab} - -To install the Chocolatey components and on-board clients, you could run an Ansible playbook. - -### ClientSetup Playbook - -```yaml ---- -- name: Chocolatey For Business Client Setup - hosts: "{{ c4b_nodes }}" - gather_facts: true - vars_prompt: - - name: license_path - prompt: "Path to Chocolatey License File" - private: no - - - name: ccm_fqdn - prompt: "FQDN to access Chocolatey Central Management, e.g. ccm.example.com" - private: no - - - name: ccm_client_salt - prompt: "Client Salt for communicating with Chocolatey Central Management" - private: yes - - - name: ccm_service_salt - prompt: "Service Salt for communicating with Chocolatey Central Management" - private: yes - - - name: nexus_password - prompt: "Password for the ChocoUser account on Sonatype Nexus Repository" - private: yes - vars: - # You can add more sources here. - chocolatey_sources: - - name: ChocolateyInternal - url: "https://{{ nexus_fqdn | default(ccm_fqdn) }}:8443/repository/ChocolateyInternal/index.json" - user: "{{ nexus_user | default('chocouser') }}" - password: "{{ nexus_password | mandatory }}" - self_service: true - - # You can add more configuration settings here. - chocolatey_config: - - cacheLocation: C:\ProgramData\chocolatey\choco-cache - - commandExecutionTimeoutSeconds: 14400 - - backgroundServiceAllowedCommands: install,upgrade,uninstall - - # You can add more features to enable or disable here. - chocolatey_features: - - showNonElevatedWarnings: disabled - - useBackgroundService: enabled - - useBackgroundServiceWithNonAdministratorsOnly: enabled - - allowBackgroundServiceUninstallsFromUserInstallsOnly: enabled - - excludeChocolateyPackagesDuringUpgradeAll: enabled - - # If you'd prefer to use a non-latest version of Chocolatey, you can specify it here. - chocolatey_version: latest - - # When set to true, deploys Chocolatey GUI and the Chocolatey GUI licensed extension. - install_gui: true - - # An accessible copy of the Dotnet 4.8 installer. - ndp48_location: https://download.visualstudio.microsoft.com/download/pr/2d6bb6b2-226a-4baa-bdec-798822606ff1/8494001c276a4b96804cde7829c04d7f/ndp48-x86-x64-allos-enu.exe - - tasks: - - name: Ensure a valid Chocolatey for Business License - block: - - name: Get Chocolatey License - ansible.builtin.set_fact: - license_content: "{{ lookup('file', license_path) }}" - when: license_content is not defined and license_path is defined - delegate_to: localhost - - - name: Get Chocolatey License Expiration - ansible.builtin.set_fact: - license_expiry: "{{ license_content | regex_search('expiration=\".+?\"') | regex_replace('expiration=\"(.+)\"', '\\1') | trim() }}" - when: license_content is defined - delegate_to: localhost - - - name: Test License Expiry - ansible.builtin.assert: - that: - - license_expiry is defined - - license_expiry | to_datetime('%Y-%m-%dT%H:%M:%S.0000000') - - license_expiry > ansible_date_time.iso8601 - quiet: true - when: license_expiry is defined - delegate_to: localhost - - - name: Ensure choco-setup Directory - ansible.windows.win_tempfile: - state: directory - suffix: choco-setup - register: choco_setup - - - name: Ensure Dotnet 4.8 - ansible.windows.win_powershell: - parameters: - NetFx48InstallerFile: "{{ ndp48_location | default('https://download.visualstudio.microsoft.com/download/pr/2d6bb6b2-226a-4baa-bdec-798822606ff1/8494001c276a4b96804cde7829c04d7f/ndp48-x86-x64-allos-enu.exe') }}" - WorkingDirectory: "{{ choco_setup.path }}" - script: | - param($NetFx48InstallerFile, $WorkingDirectory) - - if ((Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full" -ErrorAction SilentlyContinue).Release -lt 528040) { - Write-Warning ".NET Framework 4.8 is required for Chocolatey. Installing .NET Framework 4.8..." - - # Attempt to download the installer if it doesn't exist locally - if (-not (Test-Path $NetFx48InstallerFile)) { - try { - $DownloadArgs = @{ - Uri = $NetFx48InstallerFile - OutFile = Join-Path $WorkingDirectory $(Split-Path $NetFx48InstallerFile -Leaf) - UseBasicParsing = $true - } - if (-not (Test-Path $DownloadArgs.OutFile)) { - Invoke-WebRequest @DownloadArgs -ErrorAction Stop - } - $NetFx48InstallerFile = $DownloadArgs.OutFile - } catch { - $Ansible.failed = $true - throw "Could not download .NET Framework 4.8" - } - } - - # Install .NET Framework 4.8 - try { - $psi = New-Object System.Diagnostics.ProcessStartInfo - $psi.WorkingDirectory = $WorkingDirectory - $psi.FileName = $NetFx48InstallerFile - $psi.Arguments = "/q /norestart" - - $s = [System.Diagnostics.Process]::Start($psi) - $s.WaitForExit() - - $Ansible.changed = $true - - if ($s.ExitCode -notin (0, 1641, 3010)) { - $Ansible.message = "$($s.StandardOutput.ReadToEnd())" + "$($s.StandardError.ReadToEnd())" - $Ansible.failed = $true - } - } catch { - $Ansible.failed = $true - throw - } - } else { - $Ansible.changed = $false - } - register: dotnet_install - - - name: Reboot Server for Prerequisites - ansible.windows.win_reboot: - when: dotnet_install.changed - - - name: Get Chocolatey Package and Install Script - ansible.windows.win_powershell: - parameters: - RepositoryUrl: "{{ chocolatey_sources[0].url }}" - ChocolateyVersion: "{{ chocolatey_version }}" - WorkingDirectory: "{{ choco_setup.path }}" - script: | - param($RepositoryUrl, $ChocolateyVersion, $WorkingDirectory) - $Ansible.Changed = $false - - # Download Chocolatey Package - $webClient = New-Object System.Net.WebClient - try { - $Credential = [PSCredential]::new( - '{{ chocolatey_sources[0].user | default('') }}', - (ConvertTo-SecureString '{{ chocolatey_sources[0].password | default('') }}' -AsPlainText -Force) - ) - $webClient.Credentials = $Credential.GetNetworkCredential() - } catch {} - - $NupkgUrl = if (-not $ChocolateyVersion -or $ChocolateyVersion -eq 'latest') { - $QueryString = "((Id eq 'chocolatey') and (not IsPrerelease)) and IsLatestVersion" - $Query = 'Packages()?$filter={0}' -f [uri]::EscapeUriString($queryString) - $QueryUrl = ($RepositoryUrl.TrimEnd('/index.json'), $Query) -join '/' # This works with Nexus hosted repositories - - [xml]$result = $webClient.DownloadString($QueryUrl) - $result.feed.entry.content.src - } else { - # Otherwise, assume the URL - "$($RepositoryUrl.Trim('/'))/chocolatey/$($ChocolateyVersion)" - } - - $NupkgPath = Join-Path $WorkingDirectory "chocolatey.zip" - if (-not (Test-Path $NupkgPath)) { - try { - $webClient.DownloadFile($NupkgUrl, $NupkgPath) - } catch { - $Ansible.Failed = $true - } - $Ansible.Changed = $true - } - - $Ansible.Result = $NupkgPath - - # Download Chocolatey Bootstrap Script - $BootstrapScript = Join-Path $WorkingDirectory "Install-Chocolatey.ps1" - $BootstrapUrl = "$($RepositoryUrl.TrimEnd('/index.json').TrimEnd('ChocolateyInternal'))choco-install/ChocolateyInstall.ps1" - if (-not (Test-Path $BootstrapScript)) { - Write-Verbose "Downloading '$($BootstrapUrl)'" - $webClient.DownloadFile($BootstrapUrl, $BootstrapScript) - $Ansible.Changed = $true - } - register: local_choco_package - - - name: Install Chocolatey - chocolatey.chocolatey.win_chocolatey: - name: chocolatey - state: "{{ 'latest' if chocolatey_version == 'latest' or chocolatey_version is undefined or chocolatey_version == omit else 'downgrade' }}" - source: "{{ chocolatey_sources[0].url | default(omit) }}" - source_username: "{{ chocolatey_sources[0].user | default(omit) }}" - source_password: "{{ chocolatey_sources[0].password | default(omit) }}" - bootstrap_script: "{{ choco_setup.path }}\\Install-Chocolatey.ps1" - environment: - chocolateyDownloadUrl: "{{ local_choco_package.result | default('') }}" - chocolateyUseWindowsCompression: 'true' - register: choco_install - ignore_errors: true - - - name: Install Chocolatey License Package - chocolatey.chocolatey.win_chocolatey: - name: chocolatey-license - state: latest - source: "{{ chocolatey_sources[0].url | mandatory }}" - source_username: "{{ chocolatey_sources[0].user | default(omit) }}" - source_password: "{{ chocolatey_sources[0].password | default(omit) }}" - when: license_content is not defined - - - name: Ensure License Directory - ansible.windows.win_file: - path: C:\\ProgramData\\chocolatey\\license\\ - state: directory - when: license_content is defined - - - name: Install Chocolatey License - ansible.windows.win_copy: - dest: "C:\\ProgramData\\chocolatey\\license\\chocolatey.license.xml" - content: "{{ license_content }}" - force: true - when: license_content is defined - - - name: Install Chocolatey.Extension - chocolatey.chocolatey.win_chocolatey: - name: chocolatey.extension - state: latest - source: "{{ chocolatey_sources[0].url | default(omit) }}" - source_username: "{{ chocolatey_sources[0].user | default(omit) }}" - source_password: "{{ chocolatey_sources[0].password | default(omit) }}" - package_params: /NoContextMenu - - - name: Set Chocolatey Features - chocolatey.chocolatey.win_chocolatey_feature: - name: "{{ item.key }}" - state: "{{ item.value }}" - with_dict: "{{ chocolatey_features }}" - - - name: Set Chocolatey Configuration - chocolatey.chocolatey.win_chocolatey_config: - name: "{{ item.key }}" - state: "{{ 'absent' if not item.value else 'present' }}" - value: "{{ item.value | default('omit') }}" - with_dict: "{{ chocolatey_config }}" - - - name: Add Chocolatey Source - chocolatey.chocolatey.win_chocolatey_source: - name: "{{ item.name }}" - source: "{{ item.url }}" - source_username: "{{ item.user | default(omit) }}" - source_password: "{{ item.password | default(omit) }}" - priority: 1 - state: present - loop: "{{ chocolatey_sources }}" - no_log: true - - - name: Install ChocolateyGUI - chocolatey.chocolatey.win_chocolatey: - name: chocolateygui - state: latest - when: install_gui is not false - - - name: Install ChocolateyGUI Extension - chocolatey.chocolatey.win_chocolatey: - name: chocolateygui.extension - state: latest - when: install_gui is not false - - - name: Disable other sources - chocolatey.chocolatey.win_chocolatey_source: - name: "{{ item }}" - state: disabled - loop: - - chocolatey - - chocolatey.licensed - - - name: Install Chocolatey Agent - chocolatey.chocolatey.win_chocolatey: - name: chocolatey-agent - state: latest - - - name: Configure Chocolatey Agent to use Chocolatey Central Management - block: - - name: Set Chocolatey Configuration - chocolatey.chocolatey.win_chocolatey_config: - name: "{{ item.key }}" - state: "{{ 'absent' if not item.value else 'present' }}" - value: "{{ item.value | default('omit') }}" - with_dict: - - CentralManagementServiceUrl: "https://{{ ccm_fqdn }}:24020/ChocolateyManagementService" - - CentralManagementClientCommunicationSaltAdditivePassword: "{{ ccm_client_salt | default(omit) }}" - - CentralManagementServiceCommunicationSaltAdditivePassword: "{{ ccm_service_salt | default(omit) }}" - no_log: true - - - name: Set Chocolatey Features - chocolatey.chocolatey.win_chocolatey_feature: - name: "{{ item.key }}" - state: "{{ item.value }}" - with_dict: - - useChocolateyCentralManagement: enabled - - useChocolateyCentralManagementDeployments: enabled -... -``` - -
- -After saving the example playbook to a file, e.g. `client-setup.yml`, you can run it with one of the following commands: - -```shell -# This will install to all available hosts. -ansible-playbook /path/to/client-setup.yml --extra-vars "c4b_nodes='*'" - -# You could specify an inventory to use, or be more specific when defining c4b_nodes. -ansible-playbook /path/to/client-setup.yml --inventory /path/to/hosts.yml --extra-vars "c4b_nodes='windows_servers'" -``` - -You will be prompted to enter the values mentioned above, but you can pass them in using `--extra-vars` instead. Please see the Ansible documentation "[Defining Variables At Runtime](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#defining-variables-at-runtime)" for further details and examples. - -> :choco-warning: **WARNING** -> -> This playbook will install Dotnet 4.8 to target hosts that don't have a compatible version installed. -> -> This will cause machines that have the dependency installed to reboot. - -::: -:::{.tab-pane .fade #scenario-two role=tabpanel aria-labelledby=scenario-two-tab} - -To install the Chocolatey components and on-board clients, you could run the `ClientSetup.ps1` script provided with your Chocolatey for Business Ansible Environment. By default, this script is stored in the newly created `choco-install` repository. - -> :choco-info: **NOTE** -> -> You can set default values for the parameters and remove the Mandatory flag if you prefer to run the script without being prompted for input. - -### PowerShell Script - -When you're ready, run the following script on the client from an elevated (Run as Administrator) PowerShell terminal: - -```powershell -param( - # The fully qualified domain name (FQDN) of the Sonatype Nexus Repository service - [Parameter(Mandatory)] - $FQDN, - - # The Password for the chocouser account on Sonatype Nexus Repository service - [Parameter(Mandatory)] - $Password, - - # The Chocolatey Central Management client communication salt, provided during deployment - [Parameter(Mandatory)] - $ClientCommunicationSalt, - - # The Chocolatey Central Management service communication salt - [Parameter(Mandatory)] - $ServiceCommunicationSalt -) - -$credential = [pscredential]::new('chocouser', ($Password | ConvertTo-SecureString -AsPlainText -Force)) -$downloader = [System.Net.WebClient]::new() -$downloader.Credentials = $credential - -$script = $downloader.DownloadString("https://$($FQDN):8443/repository/choco-install/ClientSetup.ps1") - -$params = @{ - Credential = $credential - ClientSalt = $clientCommunicationSalt - ServerSalt = $serviceCommunicationSalt -} - -& ([scriptblock]::Create($script)) @params -``` - -
- -For example, to run this locally, save the script to an accessible location (in the example below shown as `~\Downloads\ChocoOnboarding.ps1`) and run: - -```powershell -Set-ExecutionPolicy Unrestricted -Scope Process -Force -~\Downloads\ChocoOnboarding.ps1 -``` - -
-You will then be prompted for each parameter value. - -Alternatively, you could run the ClientSetup.ps1 script with Ansible. - -### Ansible Script - -An example of what to add to your Ansible tasks is shown below: - -
- -```yaml ---- -- name: Chocolatey For Business Client Setup - hosts: "{{ c4b_nodes }}" - gather_facts: true - vars_prompt: - - name: ccm_fqdn - prompt: "FQDN to access Chocolatey Central Management, e.g. ccm.example.com" - private: no - - - name: ccm_client_salt - prompt: "Client Salt for communicating with Chocolatey Central Management" - private: yes - - - name: ccm_service_salt - prompt: "Service Salt for communicating with Chocolatey Central Management" - private: yes - - - name: nexus_password - prompt: "Password for the ChocoUser account on Sonatype Nexus Repository" - private: yes - tasks: - - name: Run ClientSetup.ps1 - ansible.windows.win_powershell: - parameters: - FQDN: "{{ ccm_fqdn }}" - Password: "{{ nexus_password }}" - ClientCommunicationSalt: "{{ ccm_client_salt }}" - ServiceCommunicationSalt: "{{ ccm_service_salt }}" - script: | - param( - # The fully qualified domain name (FQDN) of the Sonatype Nexus Repository service - [Parameter(Mandatory)] - $FQDN, - - # The Password for the chocouser account on Sonatype Nexus Repository service - [Parameter(Mandatory)] - $Password, - - # The Chocolatey Central Management client communication salt, provided during deployment - [Parameter(Mandatory)] - $ClientCommunicationSalt, - - # The Chocolatey Central Management service communication salt - [Parameter(Mandatory)] - $ServiceCommunicationSalt - ) - - $credential = [pscredential]::new('chocouser', ($Password | ConvertTo-SecureString -AsPlainText -Force)) - $downloader = [System.Net.WebClient]::new() - $downloader.Credentials = $credential - - $script = $downloader.DownloadString("https://$($FQDN):8443/repository/choco-install/ClientSetup.ps1") - - $params = @{ - Credential = $credential - ClientSalt = $clientCommunicationSalt - ServerSalt = $serviceCommunicationSalt - } - - & ([scriptblock]::Create($script)) @params -... -``` - -

- -This will not be as predictable as running Ansible tasks, and will report a change regardless of the result of the script. - -::: -:::{.tab-pane .fade #scenario-three role=tabpanel aria-labelledby=scenario-three-tab} - -To install the Chocolatey components and on-board clients, you could add the example Ansible roles to a playbook. - -To do this, copy the `roles` directory from the [C4B-Ansible Repository](https://github.com/chocolatey/c4b-ansible) to the directory your playbook is saved, or to a [`roles_path`](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#storing-and-finding-roles). - -You will then be able to reference the role(s) in your playbook, as shown below: - -### Ansible Roles - -```yaml ---- -- name: Chocolatey For Business Client Setup - hosts: "{{ c4b_nodes }}" - gather_facts: true - vars: - ccm_fqdn: "chocolatey.example.com" - ccm_client_salt: !vault | - $ANSIBLE_VAULT;1.1;AES256 - ... - ccm_service_salt: !vault | - $ANSIBLE_VAULT;1.1;AES256 - ... - nexus_password: !vault | - $ANSIBLE_VAULT;1.1;AES256 - ... - tasks: - - name: Add ChocolateyAgent to Server - ansible.builtin.include_role: - name: win_chocolateyagent - vars: - license_path: \path\to\chocolatey.license.xml - ccm_hostname: "{{ ccm_fqdn }}" - client_salt: "{{ ccm_client_salt }}" - service_salt: "{{ ccm_service_salt }}" - repository: - - name: ChocolateyInternal - url: https://{{ ccm_fqdn }}:8443/repository/ChocolateyInternal/index.json - user: chocouser - password: "{{ nexus_password }}" -... -``` - -
-For further information on the roles and available parameters, please refer to the readmes: -
- -- [Win_ChocolateyLicensed](https://github.com/chocolatey/c4b-ansible/blob/main/roles/win_chocolateylicensed/README.md) -- [Win_ChocolateyAgent](https://github.com/chocolatey/c4b-ansible/blob/main/roles/win_chocolateyagent/README.md) - -::: -:::: - -This script will accomplish the following on your client: - -1. Install Chocolatey CLI from the installation script hosted in your internal raw Sonatype Nexus Repository. -1. Add the `ChocolateyInternal` source, and enable it for self-service. -1. Disable the default `chocolatey` source. -1. Install your Chocolatey license using the `chocolatey-license` package. -1. Install the Chocolatey Licensed Extension (without context menus for Package Builder). -1. Install the `ChocolateyGUI` package on the endpoint, for self-service support. -1. Install the `chocolatey-agent` package, which supports self-service and Chocolatey Central Management communication. -1. Enable and disable features related to configuring self-service access on the endpoint. -1. Setup the communication channel between the endpoint and Chocolatey Central Management, using the correct URL and salts. -1. Enable Chocolatey Central Management Deployments. diff --git a/input/en-us/c4b-environments/ansible/index.md b/input/en-us/c4b-environments/ansible/index.md deleted file mode 100644 index 36dfb7ff5a..0000000000 --- a/input/en-us/c4b-environments/ansible/index.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -Order: 40 -xref: c4b-ansible -Title: Ansible Environment -Description: Overview of the Chocolatey for Business Ansible Environment ---- - -## Summary - -This is an overview of the Chocolatey for Business Ansible Environment. - -It is a playbook and selection of modules, allowing for the speedy creation of an opinionated, pre-configured environment containing Chocolatey Central Management (CCM), a package repository (Sonatype Nexus Repository), and an automation engine (Jenkins). - -> :choco-info: **NOTE** -> -> A Chocolatey for Business Ansible Environment is a fully functional Chocolatey for Business environment; as such, it will require a business or trial license. - -## Prerequisites - -To deploy the Chocolatey for Business Ansible Environment you will need: - -* A Chocolatey for Business license, or Trial license. -* One or more existing server accessible from your Ansible host. -* The ability to create a CNAME DNS record for your chosen FQDN. -* A valid certificate for your chosen FQDN, in PFX format, with exportable private key. - -For portions of this guide using Ansible, we will assume that you either have an Ansible Execution Environment preconfigured, or are using the [dev container](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers) to execute the playbooks. You should have the latest supported version of the [Chocolatey.Chocolatey](https://galaxy.ansible.com/ui/repo/published/chocolatey/chocolatey/) Ansible collection installed, along with any additional prerequisites listed in the [requirements.txt](https://github.com/chocolatey/c4b-ansible/blob/main/requirements.txt). - -You can install the Python requirements for the module using `PIP`, e.g.: - -```sh -pip3 install --upgrade -r /requirements.txt -``` - -## Deploying the Chocolatey for Business Ansible Environment - -The Chocolatey for Business Ansible Environment is designed to deploy Chocolatey Central Management and all the suggested softwares to one or more servers within your environment, and provide methods for deploying Chocolatey for Business to your other endpoints. - -You can deploy this using Ansible Automation Platform, an existing installation of the Ansible client, or the dev container image provided within the repository (as well as a variety of other methods). - -This guide will be written as if you were using Ansible from a local installation or the dev container, but can be easily adapted to run from Automation Platform / AWX. - -> :choco-info: **NOTE** -> -> If you want to run this deployment on an environment that doesn't have access to the internet, refer to the [offline deployment](xref:c4b-ansible-offline-deployment) page and start on a Windows machine. - -### Setup - -Clone or otherwise download the `c4b-ansible` repository from [GitHub](https://github.com/chocolatey/c4b-ansible). - -```sh -git clone https://github.com/chocolatey/c4b-ansible.git -``` - -### Configuring Your Hosts - -You can deploy the Chocolatey for Business Ansible Environment to one or more servers. There are four services being installed: - -* Chocolatey Central Management -* Sonatype Nexus Repository -* Jenkins -* Optional: SQL Server Express - -#### Installing On a Single Host - -To install on a single host, create a host with the title `ccm_server`. All services will be installed to this host. There is an example of a hosts file containing a single host in the root of the repository - [hosts.yml](https://github.com/chocolatey/c4b-ansible/blob/main/hosts.yml). - -Example: - -```yaml -all: - hosts: - ccm_server: - ansible_connection: winrm - ansible_winrm_transport: ntlm - ansible_port: 5986 - ansible_winrm_scheme: https - ansible_host: chocoserver - ansible_user: ansibleuser - ansible_password: !vault | - $ANSIBLE_VAULT;1.1;AES256 - [...] -``` - -#### Installing On Multiple Hosts - -To install on multiple hosts, define hosts with the following names: - -* `ccm_server`: Chocolatey Central Management service and website -* `nexus_server`: Sonatype Nexus Repository -* `jenkins_server`: Jenkins -* `database_server`: SQL Server Express - -Example: - -```yaml -all: - vars: - ansible_connection: winrm - ansible_winrm_transport: ntlm - ansible_port: 5986 - ansible_winrm_scheme: https - ansible_user: ansibleuser - ansible_password: !vault | - $ANSIBLE_VAULT;1.1;AES256 - [...] - hosts: - ccm_server: - ansible_host: chocoserver - nexus_server: - ansible_host: nexus - jenkins_server: - ansible_host: chocorunner - database_server: - ansible_host: db1 -``` - -If any are not defined, the service will be installed on the `ccm_server` host. - -If a connection string is passed, we assume the database is set up and do not install SQL Server. - -For further details on defining Windows hosts in Ansible, see [this blog post](https://www.ansible.com/blog/connecting-to-a-windows-host) for some basics on Windows hosts and [this documentation](https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html) for further information on inventories. - -#### Using An Existing Database - -You can provide a connection string to the environment to use for storing Chocolatey Central Management data. This can have significant benefits for performance, as well as simplifying backups and load-balancing of instances. - -To use an existing database server you wish to use, follow the instructions for [creating a database](xref:ccm-database) and provide the connection string as a variable. - -### Setting Secrets - -Secrets, including credentials, for the various services will be generated during the deployment. They are stored temporarily in the `/credentials` directory within the repository, and you should store and remove them from this when the deployment is complete. - -If you would prefer to create and maintain them from scratch, you can modify the values of the following secrets within the [`/group_vars/all.yml`](https://github.com/chocolatey/c4b-ansible/blob/main/group_vars/all.yml) file: - -Example: - -```yaml -ccm_password: !vault | - $ANSIBLE_VAULT;1.1;AES256 - [...] -ccm_client_salt: !vault | - $ANSIBLE_VAULT;1.1;AES256 - [...] -ccm_service_salt: !vault | - $ANSIBLE_VAULT;1.1;AES256 - [...] -ccm_encryption_password: !vault | - $ANSIBLE_VAULT;1.1;AES256 - [...] -``` - -> :choco-info: **Note** -> -> We have shown examples of redacted secrets being stored securely using [Ansible Vault](https://docs.ansible.com/ansible/latest/vault_guide/index.html) throughout this document. They will need to be replaced with your secrets, and we'd recommend you store them securely! - -### Internalize Packages - -You can select packages to directly internalize at the end of the deployment from the [Chocolatey Community Repository](https://community.chocolatey.org/packages/). - -To do so, uncomment the example array `internalize_packages` in the `/group_vars/all.yml`, and add packages that you wish to be internalized. - -Example: - -```yaml -# Packages to Internalize -internalize_packages: -- 1password -- 7zip -- adobereader -- azcopy -- azure-cli -- firefox -- git -- notepadplusplus -- powershell -- slack -- vscode -``` - -This will result in packages matching the ID's being internalized from the Chocolatey Community Repository. - -### Deploying the Environment - -You can now run the playbook using `ansible-playbook`. If you have modified the hosts file in the base of the repository, you can run it as follows: - -```sh -ansible-playbook ./c4b-environment.yml -i ./hosts.yml -``` - -The playbook will prompt you for the location of your license, certificate, and password. After you have answered these prompts, the playbook will deploy all of the services. - -![Initial Playbook Prompts](/assets/images/c4b-ansible/playbook-prompts.jpg) - -> :choco-info: **NOTE** -> -> You can add the values to an inventory file or the playbook directly, instead of being prompted at runtime. - -### Configuring Chocolatey Central Management - -> :choco-warning: **WARNING** -> -> You cannot create users in Chocolatey Central Management until you have configured an SMTP server. To do this, please see [how to configure SMTP](xref:ccm-website#step-4.2-smtp-configuration). -> You can log in to Chocolatey Central Management using the credentials provided in the credentials document (see [Accessing Services](#accessing-services), below). - -## Accessing Services - -At this point, the Chocolatey for Business Ansible Environment should be deployed with the following accessible services: - -| Service | Initial Username | -| --------------------------------- | ---------------- | -| **Chocolatey Central Management** | ccmadmin | -| **Sonatype Nexus Repository** | admin | -| **Jenkins** | admin | - -Passwords to login to the services have been stored in the credentials directory within the root of the `c4b-ansible` repository. - -There should be a `CCM.html` file that contains a start-up guide, including initial steps and credentials for the various services. You should secure this appropriately. - -## FAQ - -### SSL Certificate - -You will need an SSL certificate for the domain you intend to use. This certificate: - -* Needs to be in the PFX format. -* Needs to include an exportable Private Key. -* Must have a password. - -You can either provide a self-signed SSL certificate, or a purchased or acquired certificate from a Certificate Authority (CA). - -#### Self-Signed SSL Certificates - -You can quickly generate a self-signed certificate on any recent Windows machine, using PowerShell. - -**PowerShell:** - -1. Open an elevated PowerShell console -1. Run code similar to the following, modifying the `-FilePath` parameter of `Export-PfxCertificate` if necessary: - -```PowerShell -$Domain = Read-Host "Enter the FQDN you plan to use to access the Chocolatey for Business Ansible Environment sites" -$Password = Read-Host "Enter a password to use for the PFX" -AsSecureString - -$Cert = New-SelfSignedCertificate -DnsName $Domain -CertStoreLocation cert:\LocalMachine\My -$Cert | Export-PfxCertificate -FilePath ~\Desktop\$($Domain).pfx -Password $Password -``` - -You can then use this generated file and the password you set to deploy your Chocolatey for Business Ansible Environment. - -> :choco-info: **NOTE** -> -> Your browser will display warnings when accessing the Chocolatey for Business Ansible Environment sites with a self-signed certificate. To stop these warnings, you need to import this certificate to the `Trusted Root Certification Authorities` store on any clients used to access the services. Unless you know what you're doing, we would strongly recommend using a certificate from a CA like [LetsEncrypt](https://letsencrypt.org/). - -#### Purchased/Acquired Certificates From a Certificate Authority - -Organizations can also opt to purchase or acquire a certificate from an external Certificate Authority (e.g. [LetsEncrypt](https://github.com/win-acme/win-acme)). -As mentioned before, you will need to ensure that the "Subject/Common Name" attribute on the SSL certificates matches the FQDN you are using. -If you have a preferred vendor for certificates, you should refer to their documentation for best practices in acquiring a certificate. - -## Common Errors and Resolutions - -### SQL Installation Stalling - -We have seen the SQL Server installation fail with code `-2068774911`, or hang indefinitely when the target server only has IPv6 DNS. - -This can be resolved by a login to the server using RDP and re-running the playbook, or by ensuring the target server has IPv4 DNS available. - -### Timeout When Downloading Jenkins Plugins - -Sometimes the downloading of Jenkins plugins times out. Rerunning the playbook again should complete this. diff --git a/input/en-us/c4b-environments/ansible/license-update.md b/input/en-us/c4b-environments/ansible/license-update.md deleted file mode 100644 index 2eb69566a3..0000000000 --- a/input/en-us/c4b-environments/ansible/license-update.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -Order: 43 -xref: c4b-ansible-license-update -Title: License Update -Description: How to Update the License in Use on Your Chocolatey for Business Ansible Environment ---- - -## Summary - -If you use the Chocolatey for Business Ansible Environment for long periods of time, the license you used to deploy it may expire and you will need to update it. - -You can either run through the process manually, or run the Chocolatey for Business Ansible Environment playbook again with a specific tag. - -## Ansible Update - -To create your updated license package with the Ansible playbook, re-run the playbook with the `licensepackage` tag and provide the path to your new Chocolatey for Business license. - -Example of running via Playbook: - -```sh -ansible-playbook ./c4b-environment.yml -i ./hosts.yml -tags licensepackage -``` - -## Manual Update -### Prerequisites - -- You will need Chocolatey CLI installed. -- You will need your new Chocolatey for Business license file. -- You will need the FQDN of your Sonatype Nexus Repository server. -- You will need the API Key for your Sonatype Nexus Repository. - -### Creating a New License Package - -Please refer to [the Chocolatey for Business Azure Environment documentation](xref:c4b-azure-license-update#creating-a-new-license-package) for creating the license package. - -### Uploading the License Package - -We now need to upload this new package to the `ChocolateyInternal` repository. Open a PowerShell terminal and run the following code (which will prompt you for information for values that are not set): - -```PowerShell -if (-not $FQDN) { - $FQDN = "$(Read-Host -Prompt 'Please enter the FQDN for the Nexus repository')" - if (([uri]$FQDN).Host) {$FQDN = ([uri]$FQDN).Host} -} -if (-not $NexusApiKey) { - $NexusApiKey = "$(Read-Host -Prompt 'Please enter the API Key to be used to push Chocolatey packages to Nexus')" -} - -$LicensePackage = (Get-Item $env:Temp\ChocolateyLicensedPackage\*.nupkg)[-1] -choco push $LicensePackage.FullName --source="https://$($FQDN):8443/repository/ChocolateyInternal/" --api-key="$NexusApiKey" --force -``` - -### Pushing the New License to Clients - -You can either rely on automation to push this package (and updated license) to your clients, or refer to [these documents](xref:ccm-deployments) to manually create a deployment. \ No newline at end of file diff --git a/input/en-us/c4b-environments/ansible/offline-deployment.md b/input/en-us/c4b-environments/ansible/offline-deployment.md deleted file mode 100644 index 0e1bd89742..0000000000 --- a/input/en-us/c4b-environments/ansible/offline-deployment.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -Order: 41 -xref: c4b-ansible-offline-deployment -Title: Preparing for an Offline Deployment -Description: How to deploy Chocolatey for Business Ansible Environment without an internet connection ---- - -## Summary - -In some environments, you won't be able to rely on downloadable resources from the internet. For these purposes, you can prepare the Chocolatey for Business Ansible Environment to be deployed without an internet connection. - -## Prerequisites - -- A Windows machine capable of running Chocolatey. -- An internet connection. -- PowerShell 5.0+. -- A Chocolatey for Business license or Trial license. -- A compatible PFX certificate to use for your deployment. - -## Preparing for Offline Deployment - -1. To begin, download or clone the `c4b-ansible` repository to your local machine. - -1. Open a PowerShell terminal and navigate to the repository directory that contains the files you downloaded, above. - -1. In the PowerShell terminal run the `OfflineInstallPreparation.ps1` script with the following arguments: - - a. `-LicensePath`: The path to your Chocolatey license file, if it's not installed in the default location. - a. `-CertificatePath`: The path to your PFX certificate. - a. `-CertificatePassword`: A `SecureString` of your PFX certificate password. - If you do not provide it, you will be prompted to enter it securely. - - ```PowerShell - .\OfflineInstallPreparation.ps1 -LicensePath ~\Downloads\chocolatey.license.xml -CertificatePath ~\Downloads\c4b.pfx - ``` - -1. Transfer the content of the repository, including the files directory, to your offline environment and deploy it as per the instructions within the [main document](xref:c4b-ansible#setup). diff --git a/input/en-us/c4b-environments/azure/certificate-update.md b/input/en-us/c4b-environments/azure/certificate-update.md deleted file mode 100644 index 2d1f3fe311..0000000000 --- a/input/en-us/c4b-environments/azure/certificate-update.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -Order: 30 -xref: c4b-azure-cert-update -Title: Certificate Update -Description: A guide to updating the certificate used in the Chocolatey for Business Azure Environment ---- - -## Summary - -When deploying a Chocolatey for Business (C4B) Azure Environment, you are asked to supply an SSL certificate. This page shows you how to update that certificate when the original is expiring or has been regenerated for any other reason. - -To perform this operation you will need to have permissions sufficient to edit Access Policies on the environment's Azure Key Vault. - -Please note that it can take some time for all of the components in your C4B Azure Environment to reflect the new certificate. - -For portions of this document using PowerShell, we assume you have installed a recent version of the [Az modules](https://www.powershellgallery.com/packages/Az/) (easily available by running `choco install az.powershell` in an elevated prompt), and have logged in to your account using `Connect-AzAccount`. You can also set a variable, `$ResourceGroupName`, to the name of the resource group you deployed the Chocolatey for Business Azure Environment to as we will use this with the PowerShell code snippets below. - -## Access Policies - -Similar to the Access Policies configuration needed to [access](xref:c4b-azure#accessing-services) the usernames and passwords for the services running in your C4B Azure Environment, you will need to configure access to manage the SSL certificate. - -You can adjust the Access Policies using the Azure Portal or PowerShell. - -### Azure Portal - -1. Navigate to the `Resource Group` that contains your C4B Azure Environment. -1. Select the Key vault. - - ![Key vault resource](/assets/images/c4b-azure/Cert-KeyVault-Resource.png) - -1. Under `Settings` on the left of the blade, select `Access Policies`. -1. Click `+ Add Access Policy`. - - ![Vault Access Policies](/assets/images/c4b-azure/Cert-KeyVault-AccessPolicies.png) - -1. Select, at a minimum, `Certificate Permissions`: `Get`, `List`, `Import`, and `Update` *(You can use a Template such as `Certificate Management`)*. - - ![Secret Permissions](/assets/images/c4b-azure/Cert-KeyVault-SecretPermissions.png) - -1. Under `Select Principal`, click `None Selected` and find your current user, and select it. -1. Click `Add`. - - ![Add Principal](/assets/images/c4b-azure/Cert-KeyVault-AddPrincipal.png) - -1. Back on the `Access Policies` blade, hit `Save` and wait for the operation to complete. - -### PowerShell - -```PowerShell -if (-not $ResourceGroupName) {$ResourceGroupName = Read-Host 'Enter the ResourceGroupName'} -$CurrentUser = (Get-AzContext).Account.Id - -# Grant access to the KeyVault, if missing -$KeyVault = Get-AzKeyVault -ResourceGroupName $ResourceGroupName | ForEach-Object {Get-AzKeyVault -VaultName $_.VaultName} -$CertPermissions = $KeyVault.AccessPolicies.Where{$_.DisplayName -like "*$CurrentUser*"}.PermissionsToCertificates -if ($CertPermissions -notcontains 'Get' -or $CertPermissions -notcontains 'List' -or $CertPermissions -notcontains 'Update' -or $CertPermissions -notcontains 'Import') { - $NewCertPermissions = $CertPermissions + @('Get', 'List', 'Update', 'Import') | Select-Object -Unique - Set-AzKeyVaultAccessPolicy -VaultName $KeyVault.VaultName -UserPrincipalName $CurrentUser -PermissionsToCertificates $NewCertPermissions -} -``` - -## Updating the Azure Key Vault - -The certificate used by most of the C4B Azure Environment is stored in the provided Azure Key Vault under the name `C4B-Azure-Certificate`. To update the certificate used by the environment, you create a new version of this certificate. - -> :choco-info: **NOTE** -> -> Please note that the new certificate must meet the same requirements as the original did during the [initial deployment](xref:c4b-azure#ssl-certificate). The certificate: -> -> * Needs to be in the PFX format. -> * Needs to include an exportable Private Key. -> * Must have a password. - -You can upload a new version of the certificate using the Azure Portal or PowerShell. - -### Azure Portal - -1. Within the Key Vault, under `Settings` on the left of the blade, select `Certificates`. -1. Select the certificate named `C4B-Azure-Certificate`. - - ![Vault Certificates](/assets/images/c4b-azure/Cert-KeyVault-Certificates.png) - -1. Click `+ New Version`. - - ![Vault Certificates New Version](/assets/images/c4b-azure/Cert-KeyVault-Cert-New.png) - -1. Change the `Method of Certificate Creation` to `Import`. -1. Upload your certificate PFX file, and provide the password needed to import it. - - ![Vault Import Certificates](/assets/images/c4b-azure/Cert-KeyVault-Cert-Import.png) - -1. Click `Create`. -1. The new certificate will now be listed as the `CURRENT VERSION` and any previous certificates will be listed under `OLDER VERSIONS`. - - ![Vault Certificate Version List](/assets/images/c4b-azure/Cert-KeyVault-Cert-Version-List.png) - -### PowerShell - -This script prompts you for the name of the Resource Group that contains your C4B Azure Environment and then opens a dialog box to select your new certificate. - -```PowerShell -if (-not $ResourceGroupName) {$ResourceGroupName = Read-Host 'Enter the ResourceGroupName'} -$KeyVault = Get-AzKeyVault -ResourceGroupName $ResourceGroupName | ForEach-Object {Get-AzKeyVault -VaultName $_.VaultName} - -$null = [System.Reflection.Assembly]::LoadWithPartialName("System.Windows.Forms") -$FileBrowser = New-Object System.Windows.Forms.OpenFileDialog -Property @{ - Title = 'Select Chocolatey for Business Azure Environment Certificate' - Filter = 'Certificate (*.pfx)|*.pfx' -} -$null = $FileBrowser.ShowDialog() - -$CertImport = @{ - VaultName = $KeyVault.VaultName - Name = 'C4B-Azure-Certificate' - FilePath = $FileBrowser.FileName -} -$null = Import-AzKeyVaultCertificate @CertImport -Password (Read-Host "Enter the certificate import password" -AsSecureString) -``` - -## Updating the Application Gateway - -The Application Gateway provided with your C4B Azure Environment needs to be updated manually, as it is not able to reference the Azure Key Vault. - -### Azure Portal - -> :choco-info: **NOTE** -> -> In addition to the certificate in a PFX format that was used in the [previous section](xref:c4b-azure-cert-update#updating-the-azure-key-vault), you will need a copy of the certificate in CER format. -> -> You can convert your existing certificate using OpenSSL (easily installed by running `choco install openssl.light`): -> -> `openssl pkcs12 -in certificate.pfx -out certificate.cer -nokeys -clcerts` -> -> You will need to edit the resulting file to remove all of the text above the `-----BEGIN CERTIFICATE-----` line. - -1. Navigate to the `Resource Group` the contains your C4B Azure Environment. -1. Select the `Application gateway`. - - ![Application Gateway resource](/assets/images/c4b-azure/Cert-AppGateway-Resource.png) - -1. Under `Settings` on the left of the blade, select `Backend settings`. -1. Select `CCMService`. - - ![Application Gateway backend settings](/assets/images/c4b-azure/Cert-AppGateway-BackendSettings.png) - -1. On the `Add Backend settings` blade, click `+ Add certificate`. - - ![Backend setting add certificate](/assets/images/c4b-azure/Cert-AppGateway-BackendCertAdd.png) - -1. Ensure `Create new` is selected and browse to the `.cer` version of your certificate. -1. Provide a descriptive `Cert name` that is different to the existing certificate. The initial certificate is called `CCMCert`. -1. Click `+ Add certificate`. - - ![Add backend certificate](/assets/images/c4b-azure/Cert-AppGateway-BackendCertDetails.png) - -1. Click the `...` (three dots) to the right of the previous certificate and choose `Delete`. -1. Click `Save`. - - ![Save new backend certificate](/assets/images/c4b-azure/Cert-AppGateway-BackendCertSave.png) - -1. Under `Settings` on the left of the blade, select `Listeners`. -1. Select `CCM`. - - ![Application Gateway listeners settings](/assets/images/c4b-azure/Cert-AppGateway-ListenersSettings.png) - -1. Ensure `SslCertificate` is the selected certificate. -1. Check `Renew or edit selected certificate`. -1. Browse to select the `.pfx` version of your certificate. -1. Enter the `Password` required to import the certificate. -1. Click `Save`. - - ![Application Gateway listeners cert update](/assets/images/c4b-azure/Cert-AppGateway-ListenersCert.png) - -1. It can take some time for the Application Gateway to update. When it has finished you will be able check that the new certificate is being served by visiting on the C4B Azure Environment [services](xref:c4b-azure#accessing-services). - -### PowerShell - -Please note that until the `Set-AzApplicationGateway` command is run, the Application Gateway will not be updated. **The update can take up to 30 minutes**, but the command should return immediately. - -```PowerShell -if (-not $ResourceGroupName) {$ResourceGroupName = Read-Host 'Enter the ResourceGroupName'} -$ApplicationGateway = Get-AzApplicationGateway -ResourceGroupName $ResourceGroupName - -$null = [System.Reflection.Assembly]::LoadWithPartialName("System.Windows.Forms") -if (-not $FileBrowser.FileName) { - $FileBrowser = New-Object System.Windows.Forms.OpenFileDialog -Property @{ - Title = 'Select Chocolatey for Business Azure Environment Certificate' - Filter = 'Certificate (*.pfx)|*.pfx' - } - $null = $FileBrowser.ShowDialog() -} - -$CertificateDetails = @{ - Name = "SslCertificate" - CertificateFile = $FileBrowser.FileName - Password = Read-Host "Enter the certificate import password" -AsSecureString -} - -# Set the listener SSL certificate -$ApplicationGateway = Set-AzApplicationGatewaySslCertificate -ApplicationGateway $ApplicationGateway @CertificateDetails - -# Convert the certificate to a CER format -$Cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new( - $CertificateDetails.CertificateFile, - $CertificateDetails.Password, - 32 # EphemeralKeySet -) -[IO.File]::WriteAllBytes(($TemporaryCerPath = New-TemporaryFile), $Cert.Export("Cert")) - -# Set the authentication certificate for the CCM service -$ApplicationGateway = Set-AzApplicationGatewayAuthenticationCertificate -ApplicationGateway $ApplicationGateway -Name "CCMCert" -CertificateFile $TemporaryCerPath - -# "Save" the new settings to the Application Gateway -$null = Set-AzApplicationGateway -ApplicationGateway $ApplicationGateway - -# Clean up the temporary CER -Remove-Item $TemporaryCerPath -``` - -## FAQ - -### I've uploaded a new certificate, why hasn't it been applied? - -Some components of the C4B Azure Environment need to select between multiple versions of a certificate when determining if an update is required. - -The determining factor is the `NotBefore` date on the certificate. The latest date is considered to belong to the newest certificate. - -You can check the `NotBefore` property of a pfx file using PowerShell: - -```PowerShell -$CertificatePath = Read-Host 'Enter the path to the certificate file' -Get-PfxCertificate -FilePath $CertificatePath | Select-Object NotBefore -``` diff --git a/input/en-us/c4b-environments/azure/client-setup.md b/input/en-us/c4b-environments/azure/client-setup.md deleted file mode 100644 index bacdc6385c..0000000000 --- a/input/en-us/c4b-environments/azure/client-setup.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -Order: 27 -xref: c4b-azure-client-setup -Title: Client Setup -Description: How to setup a client machine to use Chocolatey for Business Azure Environment -RedirectFrom: en-us/quick-deployment/azure/client-setup ---- - -## Summary - -Once you have your Chocolatey for Business Azure Environment deployed, you'll need to get clients talking to it. -To do that, you'll need to do the following on the clients: - -1. Setup DNS to allow access to the environment. -1. Install the SSL/TLS certificate, if self-signed, so clients can access HTTPS components. -1. Install Chocolatey components and configure the client for Chocolatey for Business (C4B) deployments. - -## DNS - -Ensure that you have [configured DNS](xref:c4b-azure#dns-configuration) to direct clients to your deployed environment. - -Once you've added the required CNAME record, clients should be able to access it. - -## SSL Certificate - -> :choco-info: **NOTE** -> -> If you used an SSL certificate from an external Certificate Authority (CA), or internally trusted PKI CA, your clients will automatically trust it and you can skip this section. - -If you used a self-signed certificate to deploy your Chocolatey for Business Azure Environment, you will need to import this certificate to the `Trusted Root Certification Authorities` store on the clients. - -1. Open the Microsoft Management Console (`MMC.msc`) -1. Select **File** -> **Add/Remove Snap-in...** -1. Select **Certificates** and click **Add >** -1. Choose **Computer account** and click **Next**, **Finish**, then **OK** -1. Expand **Certificates (Local Computer)** -1. Right-click **Trusted Root Certification Authorities**, and select **All Tasks** -> **Import** - - ![Importing SSL Certificate in MMC](/assets/images/c4b-azure/MMC-Import-Certificate.png) - -1. Click **Next** -1. Browse to the self-signed certificate file - 1. You may need to adjust the filetype so that you can see `.pfx` files - - ![Changing file type when browsing for certificate file in MMC](/assets/images/c4b-azure/MMC-Browse-FileType.png) - -1. Click **Next** -1. Enter the password supplied when creating the certificate -1. Click **Next**, **Next**, then **Finish** -1. Close the Microsoft Management Console - -## Client Setup Script - -To on-board clients, you run the `ClientSetup.ps1` script provided with your Chocolatey for Business Azure Environment. - -You will need the following values ready when running this script: - -* `FQDN`: The fully qualified domain name used to access your environment. -* `ccmClientCommunicationSalt`: This is the client-side salt additive. More information about this can be found in the [C4B Config Settings](xref:ccm-client#config-settings) docs. -* `ccmServiceCommunicationSalt`: This is the server-side salt additive. More information about this can be found in the [C4B Config Settings](xref:ccm-client#config-settings) docs. -* `ChocoUserPassword`: The password for the `chocouser` account which is used by the client to access your environments' Sonatype Nexus Repository service. - -Except for the `FQDN`, all of these values are available in your deployed environment's Azure Key Vault. -See [Accessing Services](xref:c4b-azure#accessing-services) for more information about retrieving values from the Vault. - -When you're ready, run the following on the client from an elevated (Run as Administrator) PowerShell session: - -```powershell -# Please fill in the following values -$fqdn = 'Replace with FQDN for your Chocolatey for Business QDE Azure Environment' -$clientCommunicationSalt = 'Your ccmClientCommunicationSalt' #This value is stored within your Azure Key Vault -$serverCommunicationSalt = 'Your ccmServiceCommunicationSalt' #This value is stored within your Azure Key Vault -$password = 'Your ChocoUserPassword' #This value is stored within your Azure Key Vault - -# Touch NOTHING below this line -$user = 'chocouser' - -$securePassword = $password | ConvertTo-SecureString -AsPlainText -Force -$credential = [pscredential]::new($user, $securePassword) -$downloader = [System.Net.WebClient]::new() -$downloader.Credentials = $credential - -$script = $downloader.DownloadString("https://$($fqdn)/nexus/repository/choco-install/ClientSetup.ps1") - -$params = @{ - Credential = $credential - ClientSalt = $clientCommunicationSalt - ServerSalt = $serverCommunicationSalt -} - -& ([scriptblock]::Create($script)) @params -``` - -This script will accomplish the following on your client: - -1. Install Chocolatey CLI from the installation script hosted in your internal raw Sonatype Nexus Repository. -1. Add the `ChocolateyInternal` source, and enable it for self-service -1. Disable the default `chocolatey` source. -1. Install your Chocolatey license using the `chocolatey-license` package. -1. Install the Chocolatey Licensed Extension (without context menus for Package Builder). -1. Install the `ChocolateyGUI` package on the endpoint, for self-service support. -1. Install the `chocolatey-agent` package, which supports self-service and Chocolatey Central Management communication. -1. Enable and disable features related to configuring self-service access on the endpoint. -1. Setup the communication channel between the endpoint and Chocolatey Central Management, using the correct URL and salts. -1. Enable Chocolatey Central Management Deployments. diff --git a/input/en-us/c4b-environments/azure/index.md b/input/en-us/c4b-environments/azure/index.md deleted file mode 100644 index 7347b9964c..0000000000 --- a/input/en-us/c4b-environments/azure/index.md +++ /dev/null @@ -1,361 +0,0 @@ ---- -Order: 20 -xref: c4b-azure -Title: Azure Environment -Description: Overview of the Chocolatey for Business Azure Environment -RedirectFrom: - - en-us/quick-deployment/azure - - en-us/quick-deployment/azure/index.html ---- - -## Summary - -This is an overview of the Chocolatey for Business Azure Environment. - -It is a deployable resource in the [Microsoft Azure Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/chocolateysoftwareinc1605695330527.c4b_azure_qde), allowing for the speedy creation of an opinionated, pre-configured environment containing Chocolatey Central Management (CCM), a package repository (Nexus OSS), and an automation engine (Jenkins). - -> :choco-info: **NOTE** -> -> A Chocolatey for Business Azure Environment is a fully functional Chocolatey for Business environment; as such, it will require a business or trial license. - -## Prerequisites - -Currently, to deploy the Chocolatey for Business Azure Environment you will need: - -* A Chocolatey for Business License, or Trial License -* An account with [Contributor](https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#contributor) access to an Azure subscription -* The ability to create a CNAME DNS record for your chosen FQDN -* A valid certificate for your chosen FQDN, in PFX format, with exportable private key - -For portions of this document using PowerShell, we assume you have installed a recent version of the [Az modules](https://www.powershellgallery.com/packages/Az/) (easily available by running `choco install az.powershell` in an elevated prompt), and have logged in to your account using `Connect-AzAccount`. You can also set a variable, `$ResourceGroupName`, to the name of the resource group you deployed the Chocolatey for Business Azure Environment to as we will use this with the PowerShell code snippets below. - -## Deploying the Chocolatey for Business Azure Environment - -The Chocolatey for Business Azure Environment is available as a deployable resource in the [Microsoft Azure Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/chocolateysoftwareinc1605695330527.c4b_azure_qde). - -Find the [Chocolatey for Business Azure Environment](https://portal.azure.com/#blade/Microsoft_Azure_Marketplace/GalleryItemDetailsBladeNopdl/id/chocolateysoftwareinc1605695330527.c4b_azure_qde) resource, and click `Create`. You will be taken to the `Create Chocolatey for Business Azure Environment` page. - -### Basics - -Select the subscription, resource group, and region you intend to deploy to. As you need to deploy this to an empty resource group, you may need to create a new one by clicking the `Create new` button below the selector. - -![Resource Group Selector](/assets/images/c4b-azure/BasicsView-ResourceGroupSelector.png) - -By default, all resources in the resource group are deployed with 'choco' prefixing the resource name. If you'd prefer to use something else for identification you can change it here. - -> :choco-info: **NOTE** -> -> Due to constraints in naming some resources, the prefix must be 8 characters or less and contain only alphanumeric characters. - -![Naming Prefix](/assets/images/c4b-azure/BasicsView-InstanceDetails.png) - -For the environment to deploy successfully, you must have a valid Chocolatey for Business license. Select and upload your license here. - -![License Upload](/assets/images/c4b-azure/BasicsView-LicenseUpload.png) - -### Domain Configuration - -In order to connect to your new Chocolatey for Business Azure Environment, you will need to select a DNS name. Though you can connect to the Microsoft provided FQDN, there would be additional work involved in trusting the self-signed certificate used (i.e. adding the Public IP addresses' FQDN to a self-signed certificate, and ensuring this certificate was in the `Trusted Root Certification Authorities` store). - -Fill your intended domain name in, select and upload your PFX certificate, and enter the password for the certificate. - -![Custom Domain Configuration](/assets/images/c4b-azure/DomainView-CustomDomain.png) - -> :choco-info: **NOTE** -> -> The PFX certificate must contain the exportable private key, and should be protected with a password. -> Suggestions for creating a PFX certificate can be found [here](xref:c4b-azure#ssl-certificate). - -### Internalize Packages - -You can select packages to directly internalize from the [Chocolatey Community Repository](https://community.chocolatey.org/packages/). - -We offer bundles of recommended packages (see [recommendations](xref:c4b-azure-packages#recommendations) for the exact content of each bundle). - -You can then select any of the **Additional Packages**, which will be added to the bundle you choose. - -Finally, you can specify _any other_ package from the Chocolatey Community Repository in the `Specify any other packages` textbox. - -Please provide a list of Package IDs, separated with commas. - -![Package Internalization Screen](/assets/images/c4b-azure/InternalizePackagesView.png) - -### Review + create - -At this point, Azure will validate your inputs and allow you to deploy the resource. - -If there are any validation errors (e.g. missing fields), Azure will highlight the tab the issue is on. - -When validation succeeds, click `Create`. The specified environment will be deployed. This can take around half an hour, depending on how many packages are being internalized. - -## DNS Configuration - -You should create a CNAME DNS record for the domain you specified on the earlier Domain Configuration page. - -You can get the FQDN using the [Azure Portal](https://portal.azure.com), or via PowerShell: - -**Portal:** - -1. Navigate to the Resource Group -1. Select the resource with type `Public IP Address` -1. Copy the `DNS name` from the `Essentials` panel at the top of the blade - -![Public IP Address](/assets/images/c4b-azure/PublicIPAddress-EssentialsView.png) - -**PowerShell:** - -1. Run the following PowerShell: - -```PowerShell -if (-not $ResourceGroupName) {$ResourceGroupName = Read-Host 'Enter the ResourceGroupName'} -Get-AzPublicIpAddress -ResourceGroupName $ResourceGroupName | Select-Object -ExpandProperty DnsSettings | Select-Object -ExpandProperty Fqdn -``` - -### Creating a CNAME record - -You should now create a CNAME record for this FQDN. The exact method for this will vary depending on your domain registrar. -Please see the table below for links to help from some popular registrars: - -| Registrar | Documentation | -| ---------- | ------------- | -| GoDaddy | [Add a CNAME record](https://godaddy.com/help/add-a-cname-record-19236) | -| NameCheap | [How to Create a CNAME Record For Your Domain](https://www.namecheap.com/support/knowledgebase/article.aspx/9646/2237/how-to-create-a-cname-record-for-your-domain/) | -| Cloudflare | [Managing DNS records in Cloudflare](https://support.cloudflare.com/hc/en-us/articles/360019093151-Managing-DNS-records-in-Cloudflare#h_60566325041543261564371) | -| Bluehost | [How To Create & Edit CNAME](https://my.bluehost.com/hosting/help/resource/714) | -| 123-reg | [Creating a CNAME record](https://www.123-reg.co.uk/support/domains/how-do-i-set-up-a-cname-record-on-my-domain-name/) | - -If you need help with another registrar, we recommend searching for their documentation, or reaching out to their support. - -### Configuring Chocolatey Central Management - -> :choco-warning: **WARNING** -> -> You cannot create users in Chocolatey Central Management until you have configured an SMTP server. To do this, please see [how to configure SMTP](xref:ccm-website#step-4.2-smtp-configuration). -> You can log in to Chocolatey Central Management using the credentials provided in the KeyVault (see [Accessing Services](#accessing-services), below). - -## Accessing Services - -At this point, your environment should be deployed. You should be able to access the following services: - -| Service | Address | Initial Username | -| --------------------------------- | :----------------------- | ---------------- | -| **Chocolatey Central Management** | https://\/ | ccmadmin | -| **Sonatype Nexus** | https://\/nexus | admin | -| **Jenkins** | https://\/jenkins | admin | - -Passwords to log in to the services have been stored in the KeyVault deployed to your Resource Group. - -You can access these passwords either via the Azure Portal, or with PowerShell. - -**Portal:** - -1. Navigate to the Resource Group -1. Select the KeyVault -1. Under `Settings` on the left of the blade, select `Access Policies` -1. Click `+ Add Access Policy` - - ![Vault Access Policies](/assets/images/c4b-azure/KeyVault-AccessPolicies.png) - -1. Select, at a minimum, `Secret Permissions`: `Get` and `List` *(You can use a Template such as `Secret Management`)* - - ![Secret Permissions](/assets/images/c4b-azure/KeyVault-SecretPermissions.png) - -1. Under `Select Principal`, click `None Selected` and find your current user, and select it -1. Click `Add` - - ![Add Principal](/assets/images/c4b-azure/KeyVault-AddPrincipal.png) - -1. Back on the `Access Policies` blade, hit `Save` and wait for the operation to complete - -You can now view and access the secrets in this KeyVault. - -![Secrets in Vault](/assets/images/c4b-azure/KeyVault-Secrets.png) - -1. Under `Settings` on the left of the blade, select `Secrets` -1. For each Password you want to retrieve (e.g. nexusPassword) - 1. Select the secret - 1. Select the current version - 1. Either click `Show Secret Value` or use the `Copy to Clipboard` button to retrieve the secret - -**PowerShell:** - -1. Run PowerShell similar to the following: - -```PowerShell -if (-not $ResourceGroupName) {$ResourceGroupName = Read-Host 'Enter the ResourceGroupName'} -$CurrentUser = (Get-AzContext).Account.Id - -# Grant access to the KeyVault, if missing -$KeyVault = Get-AzKeyVault -ResourceGroupName $ResourceGroupName | ForEach-Object {Get-AzKeyVault -VaultName $_.VaultName} -if ($KeyVault.AccessPolicies.Where{$_.DisplayName -like "*$CurrentUser*"}.PermissionsToSecrets -notcontains 'get') { - Set-AzKeyVaultAccessPolicy -VaultName $KeyVault.VaultName -UserPrincipalName $CurrentUser -PermissionsToSecrets @('get') -} - -Write-Host "Chocolatey for Business Azure Environment Passwords for '$($KeyVault.ResourceGroupName)':" -@{ - CCM = Get-AzKeyVaultSecret -VaultName $KeyVault.VaultName -Name ccmPassword -AsPlainText - Nexus = Get-AzKeyVaultSecret -VaultName $KeyVault.VaultName -Name nexusPassword -AsPlainText - Jenkins = Get-AzKeyVaultSecret -VaultName $KeyVault.VaultName -Name jenkinsPassword -AsPlainText -} -``` - -*or* Download and use [Get-AzLabCredential.ps1](https://gist.githubusercontent.com/JPRuskin/a8e438c534a471749fe3c38c948882e8/raw/Get-AzLabCredential.ps1) (which automatically handles permissions), as follows: - -```PowerShell -if (-not $ResourceGroupName) {$ResourceGroupName = Read-Host 'Enter the ResourceGroupName'} -$CcmCredential = .\Get-AzLabCredential.ps1 -ResourceGroupName $ResourceGroupName -SecretPrefix ccm -$NexusCredential = .\Get-AzLabCredential.ps1 -ResourceGroupName $ResourceGroupName -SecretPrefix nexus -$JenkinsCredential = .\Get-AzLabCredential.ps1 -ResourceGroupName $ResourceGroupName -SecretPrefix jenkins -``` - -## FAQ - -### SSL Certificate - -You will need an SSL certificate for the domain you intend to use. This certificate: - -* Needs to be in the PFX format -* Needs to include an exportable Private Key -* Must have a password - -You can either provide a self-signed SSL certificate, or a purchased or acquired certificate from a Certificate Authority (CA). - -#### Self-Signed SSL Certificates - -You can quickly generate a self-signed certificate on any recent Windows computer, using PowerShell. - -**PowerShell:** - -1. Open an elevated PowerShell console -1. Run code similar to the following, modifying the filepath if necessary: - -```PowerShell -$Domain = Read-Host "Enter the FQDN you plan to use to access the Chocolatey for Business Azure Environment sites" -$Password = Read-Host "Enter a password to use for the PFX" -AsSecureString - -$Cert = New-SelfSignedCertificate -DnsName $Domain -CertStoreLocation cert:\LocalMachine\My -$Cert | Export-PfxCertificate -FilePath ~\Desktop\$($Domain).pfx -Password $Password -``` - -You can then use this generated file and the password you set to deploy your Chocolatey for Business Azure Environment. - -You can also use a Microsoft Azure KeyVault to create a self-signed certificate by following the steps in Microsoft's documentation using the [Portal](https://docs.microsoft.com/en-us/azure/key-vault/certificates/quick-create-portal) or [Azure PowerShell](https://docs.microsoft.com/en-us/azure/key-vault/certificates/quick-create-powershell). - -> :choco-info: **NOTE** -> -> Your browser will display warnings when accessing the Chocolatey for Business Azure Environment sites with a self-signed certificate. To stop these warnings, you need to import this certificate to the `Trusted Root Certification Authorities` store on machines used to access the management sites. - -#### Purchased/Acquired Certificates from CA - -Organizations can also opt to purchase or acquire a certificate from an external Certificate Authority (e.g. [LetsEncrypt](https://github.com/win-acme/win-acme)). -As mentioned before, you will need to ensure that the "Subject/Common Name" attribute on the SSL certificates matches the FQDN you are using. -If you have a preferred vendor for certificates, you should refer to their documentation for best practices in acquiring a certificate. - -You can also use a Microsoft Azure KeyVault and one of the [partnered CA Providers](https://docs.microsoft.com/en-us/azure/key-vault/certificates/create-certificate#partnered-ca-providers) to create and fulfil a certificate request, though this may require additional configuration for your environment. - -### How much does it cost? - -A ballpark estimate comes to around $350 per month for the deployed infrastructure, after the 0.20.0 release. - -| Version | Estimated Cost | Date | -| -------- | -------------- | ------------------------ | -| ≤ 0.19.0 | $170 | 2021-07-29 -> 2023-07-17 | -| ≥ 0.20.0 | $350 | 2023-08-17 -> | - -This is due to the deprecation of the Application Gateway v1, which cost significantly less than the v2. - -Using methods such as [Azure Reservations](https://docs.microsoft.com/en-us/azure/cost-management-billing/reservations/save-compute-costs-reservations), [Hybrid Benefit](https://azure.microsoft.com/en-gb/pricing/hybrid-benefit/), or [Dev-Test Subscriptions](https://azure.microsoft.com/en-gb/pricing/dev-test/#overview) can cut the overall cost significantly. - -This is based on: - -* Using a `Standard B4ms` VM size -* Deploying to a standard Pay-As-You-Go subscription -* Deploying to the `East US` location - -### Can I change my public IP address in the Application Gateway from Dynamic to Static? - -The only way to accomplish this is by setting the public IP address statically _from the start_. Once the public IP address is created, the application gateway does not support changing it. More information can be found [in the Microsoft documentation here.](https://learn.microsoft.com/en-us/azure/virtual-network/ip-services/configure-public-ip-application-gateway) - -What _can_ be done is creating a CNAME record pointing at the existing DNS record of the Application Gateway. For assistance in setting this CNAME DNS record, please see our [supporting documentation](xref:c4b-azure#dns-configuration). - -## Common Errors and Resolutions - -### Jenkins jobs fail to run after upgrade to Chocolatey CLI v2.0.0 - -As of version 2.0.0 of Chocolatey CLI, the `choco list` command only lists local packages. The Jenkins scripts included in the C4B Azure Environment prior to version 0.19.0 used this command when interrogating the environment's Nexus repositories. This results in the Jenkins jobs that use these scripts failing to run after updating Chocolatey CLI on ChocoServer itself to version 2.0.0 or above. - -To fix these scripts, you need to install a package called `chocolatey-licensed-jenkins-scripts` on ChocoServer. Start by internalizing it: - -1. Ensure you have your login credentials for Jenkins and Chocolatey Central Management, as described in the [Accessing Services](#accessing-services) section. -1. Log into Jenkins at `https:///jenkins` -1. Click the green "play" triangle to the right of the `Internalize packages from the Chocolatey Community and Licensed Repositories` job - - ![Location of Jenkins job play button](/assets/images/c4b-azure/Jenkins-Play-Button.png) - -1. Enter `chocolatey-licensed-jenkins-scripts` under the `P_PKG_LIST` parameter -1. Change the `P_DST_URL` parameter so that it ends with `ChocolateyInternal` rather than `ChocolateyTest`, this is being changed because the job that promotes packages between these repositories will not work if you have already upgraded to Chocolatey CLI v2.0.0 or above -1. Click `Build` - - ![Example of settings for the Internalize Packages Jenkins job](/assets/images/c4b-azure/Jenkins-Job-Fix-Internalize.png) - -> :choco-info: **NOTE** -> -> You may wish to run this job a second time, leaving the `P_DST_URL` as its default value. This will allow future updates to the `chocolatey-licensed-jenkins-scripts` package to be automatically internalized. - -Now you need to deploy the `chocolatey-licensed-jenkins-scripts` package to ChocoServer: - -1. Log into Chocolatey Central Management at `https:///` -1. Navigate to `Groups` and create a group the contains only ChocoServer if that does not already exist -1. Create a [Deployment Plan](xref:ccm-deployments) that targets the group containing ChocoServer -1. Add a basic step, selecting the `choco install` command and specifying the package name `chocolatey-licensed-jenkins-scripts` -1. Move this Deployment Plan to the Ready [state](xref:ccm-deployments#deployment-states) and then run it - -### Status Message: Exist soft deleted vault with the same name. (Code:ConflictError) - -This can happen when you've deployed a Chocolatey for Business Azure Environment, deleted the Resource Group, and then redeployed it with the same name. - -You can either purge the KeyVault in the GUI, or use the PowerShell Az modules as follows: - -**PowerShell:** - -```PowerShell -if (-not $ResourceGroupName) {$ResourceGroupName = Read-Host 'Enter the ResourceGroupName'} -Get-AzKeyVault -InRemovedState | Where-Object { - $_.ResourceId -match "/resourceGroups/$($ResourceGroupName)/" -} | ForEach-Object { - Remove-AzKeyVault -Name $_.VaultName -Location $_.Location -InRemovedState -Force -} -``` - -**Portal:** - -1. Open the [Azure Portal](https://portal.azure.com) in a browser, and navigate to the [KeyVault](https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults) resource view. -1. Click `Manage Deleted Vaults` -1. Select the Subscription the KeyVault was contained in -1. Select the KeyVault to purge, and click `Purge`, then confirm by clicking `Delete` - -### Wait-CCM: 'http://ChocoServer/' was not accessible - -We have seen an occasional issue with IISReset that cannot be replicated. This results in CCM setup stalling. - -> Restart attempt failed. -> Access denied, you must be an administrator of the remote computer to use this -> command. Either have your account added to the administrator local group of -> the remote computer or to the domain administrator global group. - -If you see this error, you should redeploy the resource. - -### Environment VM unable to start due to missing secret (Error: KeyVaultSecretDoesNotExist) - -During the deployment of the Chocolatey for Business Azure Environment your supplied certificate is converted from a [secret](https://learn.microsoft.com/en-us/azure/key-vault/secrets/about-secrets) object to a [certificate](https://learn.microsoft.com/en-us/azure/key-vault/certificates/about-certificates) object within the environment's [KeyVault](https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults) - -The Chocolatey for Business Azure Environment's Virtual Machine may retain a reference to the certificate from prior to the conversion, and if it is shut down then it will not be able to start again due to the referenced secret no longer existing. - -To fix this, use the PowerShell Az modules as follows: - -```PowerShell -if (-not $ResourceGroupName) { - $ResourceGroupName = Read-Host 'Enter the ResourceGroupName' -} -Get-AzVM -ResourceGroupName $ResourceGroupName | Remove-AzVMSecret | Update-AzVM -``` diff --git a/input/en-us/c4b-environments/azure/license-update.md b/input/en-us/c4b-environments/azure/license-update.md deleted file mode 100644 index bb09914c28..0000000000 --- a/input/en-us/c4b-environments/azure/license-update.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -Order: 31 -xref: c4b-azure-license-update -Title: License Update -Description: How to update the license in use on your Chocolatey for Business Azure Environment ---- - -## Summary - -If you use the Chocolatey for Business Azure Environment for long periods of time, the license you used to deploy it may expire and you will need to update it. - -### Prerequisites - -- You will need Chocolatey CLI installed. -- You will need your new Chocolatey for Business license file. -- You will need the FQDN of your Chocolatey for Business Azure Environment. -- You will need the API Key for your Nexus repository (or access to the Resource Group hosting your Azure Key Vault to be able to [retrieve it](xref:c4b-azure#accessing-services)). - -## Creating a New License Package - -When you initially deploy a Chocolatey for Business Azure Environment, you upload your Chocolatey for Business license. This is then used to create a Chocolatey package that installs the license on your nodes. - -We will need to create an updated version of the package, which will overwrite the previous version of the license on install. - -Open a PowerShell window and run the following code (which will prompt you for information for values that are not set): - -```PowerShell -if (-not $LicensePath) { - $LicensePath = "$(Read-Host -Prompt 'Please enter the path to your license file')" -} - -# Generate the license package layout -$WorkingDirectory = Join-Path $env:Temp "ChocolateyLicensedPackage" -if (-not (Test-Path $WorkingDirectory)) { - $null = New-Item -Path $WorkingDirectory -ItemType Directory -} - -$PackageDirectory = Join-Path $WorkingDirectory "chocolatey-license" - -$ToolsDir = Join-Path $PackageDirectory "tools" -if (-not (Test-Path $ToolsDir)) { - $null = New-Item $ToolsDir -ItemType Directory -} - -Set-Content -Path $ToolsDir\chocolateyInstall.ps1 -Encoding UTF8 -Value @' -$ErrorActionPreference = "Stop" -$ToolsDir = Split-Path -Parent $MyInvocation.MyCommand.Definition - -if (-not (Test-Path $env:ChocolateyInstall\license -PathType Container)) { - $null = New-Item $env:ChocolateyInstall\license -ItemType Directory -Force -} -Copy-Item -Path $ToolsDir\chocolatey.license.xml -Destination $env:ChocolateyInstall\license\chocolatey.license.xml -Force -'@ - -Set-Content -Path $ToolsDir\chocolateyUninstall.ps1 -Encoding UTF8 -Value @' -Remove-Item -Path "$env:ChocolateyInstall\license\chocolatey.license.xml" -Force -'@ - -Set-Content -Path $PackageDirectory\chocolatey-license.nuspec -Encoding UTF8 -Value @' - - - - chocolatey-license - 1.0.0 - Chocolatey License - Chocolatey Software, Inc - chocolatey license - Installs the Chocolatey commercial license file. - This package ensures installation of the Chocolatey commercial license file. -This should be installed internally prior to installing other packages, directly after Chocolatey is installed and prior to installing `chocolatey.extension` and `chocolatey-agent`. -The order for scripting is this: -* chocolatey -* chocolatey-license -* chocolatey.extension -* chocolatey-agent -If items are installed in any other order, it could have strange effects or fail. - - - - - - -'@.Trim() - -# Update the license -Copy-Item -Path $LicensePath -Destination $ToolsDir\chocolatey.license.xml -Force - -# Get license expiration date and node count -[xml]$licenseXml = Get-Content -Path $LicensePath -$licenseExpiration = [datetimeoffset]::Parse("$($licenseXml.SelectSingleNode('/license').expiration) +0") -$null = $licenseXml.license.name -match "(?<=\[).*(?=\])" -$licenseNodeCount = $Matches.Values -replace '\s[A-Za-z]+','' - -if ($licenseExpiration -lt [datetimeoffset]::UtcNow) { - Write-Warning "THE LICENSE FILE AT '$LicensePath' is EXPIRED. This is the file used by this script to generate this package, not at '$licensePackageFolder'" - Write-Warning "Please update the license file correctly in the environment FIRST, then rerun this script." - throw "License is expired as of $($licenseExpiration.ToString()). Please use an up to date license." -} - -if (-not $LicensePackageVersion) { - $LicensePackageVersion = ($licenseExpiration | Get-Date -Format 'yyyy.MM.dd') + '.' + "$licenseNodeCount" -} - -# Pack everything up -choco pack $WorkingDirectory\chocolatey-license\chocolatey-license.nuspec --output-directory="$WorkingDirectory" --version="$LicensePackageVersion" -``` - -## Uploading the License Package - -We now need to upload this new package to the Nexus repository. Open a PowerShell window and run the following code (which will prompt you for information for values are not set): - -```PowerShell -if (-not $FQDN) { - $FQDN = "$(Read-Host -Prompt 'Please enter the FQDN for the Chocolatey for Business Azure Environment application')" - if (([uri]$FQDN).Host) {$FQDN = ([uri]$FQDN).Host} -} -if (-not $NexusApiKey) { - $NexusApiKey = "$(Read-Host -Prompt 'Please enter the API Key to be used to push Chocolatey packages to Nexus')" -} - -$LicensePackage = (Get-Item $env:Temp\ChocolateyLicensedPackage\*.nupkg)[-1] -choco push $LicensePackage.FullName --source="https://$($FQDN)/nexus/repository/ChocolateyInternal/" --api-key="$NexusApiKey" --force -``` - -## Pushing the New License to Nodes - -You can either rely on automation to push this package (and updated license) to your nodes, or refer to [these documents](xref:ccm-deployments) to trigger a deployment manually. diff --git a/input/en-us/c4b-environments/azure/packages.md b/input/en-us/c4b-environments/azure/packages.md deleted file mode 100644 index 4a85a2f0fe..0000000000 --- a/input/en-us/c4b-environments/azure/packages.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -Order: 26 -xref: c4b-azure-packages -Title: Package Selection -Description: A summary of the package offerings for the Chocolatey for Business Azure Environment -RedirectFrom: en-us/quick-deployment/azure/packages ---- - -## Summary - -When deploying the Chocolatey for Business Azure Environment, you are prompted to select [packages to internalize](xref:c4b-azure#internalize-packages). - -This page shows the packages we bundle as recommendations, and discusses how to source other packages to automatically publish to your new Chocolatey for Business Azure Environment. - -## Recommendations - -We provide bundles of packages that are commonly used by Chocolatey for Business customers: - -| Bundle | Contains | -| ------- | ----------------------------------------------------------------- | -| All | Google Chrome
Mozilla Firefox
Microsoft Edge
Microsoft VS Code
Microsoft PowerShell
Microsoft Office 365 ProPlus
Notepad++
Adobe Reader
Slack
Microsoft Teams
Zoom
Google Drive
Microsoft OneDrive
Skype
VSCode PowerShell
Git
GIMP
VLC
SysInternals
Azure-CLI
AzCopy
1password
PuTTY
Java Runtime Environment | -| Minimal | Google Chrome
Microsoft Edge
Microsoft VS Code
Microsoft PowerShell
Microsoft Office 365 ProPlus
Notepad++
Adobe Reader
Slack
Microsoft Teams
Zoom | -| None | - | - -You can remove any of these packages from your repository without using them by logging into Nexus, browsing to the `ChocolateyTest` and `ChocolateyInternal` repositories, and deleting the package from each. - -## Custom Packages - -You can add custom packages using the `Specify any other packages` textbox. - -Please provide these as a comma-separated list, e.g. - -```text -nexus-repository, notepadplusplus, sublimetext3 -``` - -> :choco-warning: **WARNING** -> -> We recommend you review and test all packages before internalizing and deploying them from the [Chocolatey Community Repository](https://community.chocolatey.org/packages). - -## Adding Packages Post-Deployment - -You can download and internalize packages after the deployment of your environment. - -To do so, log into Jenkins at `https:///jenkins`, and click the `Schedule a Build...` icon on the right of the `Internalize packages from the Community Repository` job. This will take you to a screen where you can add Package IDs as a semicolon-separated list to the `P_PKG_LIST` parameter, e.g. - -```text -nexus-repository; notepadplusplus; sublimetext3 -``` - -Start the internalize job by clicking `Build`. - -The specified packages will then be downloaded and pushed to your ChocolateyTest repository, ready for testing, and then be promoted to the ChocolateyInternal repository either by you or by the `Update production repository` job. - -There are further details on these default jobs [here](xref:automate-package-internalization#create-jenkins-jobs). diff --git a/input/en-us/c4b-environments/azure/rdp.md b/input/en-us/c4b-environments/azure/rdp.md deleted file mode 100644 index f9fcb91712..0000000000 --- a/input/en-us/c4b-environments/azure/rdp.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -Order: 28 -xref: c4b-azure-rdp -Title: RDP Access -Description: A guide to accessing RDP in the Chocolatey for Business Azure Environment -RedirectFrom: en-us/quick-deployment/azure/rdp ---- - -## Summary - -After deploying a Chocolatey for Business Azure Environment, you may wish to link the machine to an existing Active Directory domain or install monitoring software. This page will show you how to gain access to the primary VM within the environment via Remote Desktop Protocol (RDP). - -We will assume you know [how to retrieve passwords from your environment](xref:c4b-azure#accessing-services). In order to connect, you need the VM username and password (stored in the deployed Azure Key Vault). - -## Azure Portal - -We need to add a publicly accessible IP address to the VM, and add a rule to the Network Security Group (NSG) to allow connections. - -First we will add the IP address: - -1. In the [Azure Portal](https://portal.azure.com), navigate to the Resource Group containing your deployed Chocolatey for Business Azure Environment. -1. Select the VM's network interface (which should be called `choco-vm-nic` by default), and open the `IP configurations` panel. - - ![Open IP Configurations](/assets/images/c4b-azure/Rdp-IpConfiguration.png) - -1. Select the IP configuration (`ipconfig1` by default), and under `Public IP address settings` click `Associate`. - - ![Create IP Address](/assets/images/c4b-azure/Rdp-IpCreation.png) - -1. Click `Create new`, and create a basic IP address. For future examples, I have named this IP `choco-vm-ip`. - - | Key | Value | - | ------------------- | -------------------------------- | - | Name | choco-vm-ip _(or similar)_ | - | Sku | Basic | - | Assignment | Dynamic | -1. Click `Save`. - -On returning to the network interface overview, a `Public IP address` should now be visible. Make a note of the value. - -Now we will add a rule to the NSG. If you do not already know your current public IP address, you can find out by visiting [ipconfig.me](https://ifconfig.me/ip). - -1. Navigate back to your Resource Group in the Azure Portal -1. Select the `Network security group`, and open the `Inbound security rules` panel. - - ![Create IP Address](/assets/images/c4b-azure/Rdp-NsgRuleAddition.png) - -1. Click `Add` and fill in at least the following details: - - | Key | Value | - | ------------------- | -------------------------------- | - | Service | RDP | - | Source | IP Addresses | - | Source IP addresses | _Your current public IP address_ | - | Name | RDPAccess _(or similar)_ | -1. Click `Add` at the bottom of the panel - -You should now be able to try [Connecting to the VM](xref:c4b-azure-rdp#connecting-to-the-vm) - -## PowerShell - -For the sake of this section, we will assume that you have installed an up-to-date version of [Az modules](https://www.powershellgallery.com/packages/Az) and your session is authenticated with an account that has access to your Chocolatey for Business Azure Environment. We also assume that you haven't made significant modifications to the deployed resources. - -To begin, we need to create a Public IP address for the VM. - -```PowerShell -if (-not $ResourceGroupName) { - $ResourceGroupName = Read-Host 'Enter the ResourceGroupName' -} - -# There should only be one network interface in the resource group. -if (-not ($NI = Get-AzNetworkInterface -ResourceGroupName $ResourceGroupName -Name *-nic)) { - Write-Error "No Network Interface matching '*-nic' found in '$($ResourceGroupName)'. Please ensure deployment is complete." -} - -if (-not $NI.IpConfigurations[0].PublicIpAddress.Id) { - # If there is no public IP address assigned, we create one. - if (-not ($VMPublicIp = Get-AzPublicIpAddress -ResourceGroupName $ResourceGroupName -Name 'TempIP')) { - $ResourceGroup = Get-AzResourceGroup -Name $ResourceGroupName - $VMPublicIp = New-AzPublicIpAddress -ResourceGroupName $ResourceGroupName -Name 'TempIP' -Location $ResourceGroup.Location -AllocationMethod Dynamic - } - - # And assign it to the VM's network interface - $NI.IpConfigurations[0].PublicIpAddress = $VMPublicIp - $NI = Set-AzNetworkInterface -NetworkInterface $NI -} -``` - -We should then create a NSG rule to allow traffic from our current IP to the VM over the port used for RDP (3389). If you want to create the rule for another IP address, you should change the value of `$IPAddress` before running the `Add` and `Set` commands. - -```PowerShell -if (-not $ResourceGroupName) { - $ResourceGroupName = Read-Host 'Enter the ResourceGroupName' -} -# Look up your current Public IP address -$IPAddress = (Invoke-WebRequest -Uri "https://ifconfig.me/ip").Content - -# Find the deployed Network Security Group -$Group = Get-AzNetworkSecurityGroup -ResourceGroupName $ResourceGroupName - -# And add a rule allowing RDP from your current Public IP address -$RdpRule = @{ - Name = "$($env:UserName)-RDP" - Direction = 'Inbound' - Priority = (($Group.SecurityRules.Priority | Sort-Object)[0] - 1) - Access = 'Allow' - SourceAddressPrefix = $IPAddress - SourcePortRange = '*' - DestinationAddressPrefix = '*' - DestinationPortRange = '3389' - Protocol = 'TCP' -} -$null = Add-AzNetworkSecurityRuleConfig @RdpRule -NetworkSecurityGroup $Group -$null = Set-AzNetworkSecurityGroup -NetworkSecurityGroup $Group -``` - -Finally, you can find the IP address to connect to by running the following code: - -```PowerShell -if (-not $ResourceGroupName) { - $ResourceGroupName = Read-Host 'Enter the ResourceGroupName' -} -# Look up the new Public IP address for the VM's network interface -$NI = Get-AzNetworkInterface -ResourceGroupName $ResourceGroupName -Name *-nic -$IPAddress = Get-AzPublicIpAddress -ResourceGroupName $ResourceGroupName -Name $NI.IpConfigurations.PublicIpAddress.Id.Split('/')[-1].IPAddress - -Write-Host "The IP Address to connect to is $($IPAddress)" -``` - -## Connecting to the VM - -> :choco-info: **NOTE** -> It can sometimes take a few minutes for the Network Security Group rules to be updated. - -Finally, use the IP address that we found in the previous steps to [connect to the VM](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/connect-logon) using the IP address you procured in the previous steps, using [the credential from the Azure Key Vault](xref:c4b-azure#accessing-services). diff --git a/input/en-us/c4b-environments/azure/release-notes.md b/input/en-us/c4b-environments/azure/release-notes.md deleted file mode 100644 index 2388b9fe89..0000000000 --- a/input/en-us/c4b-environments/azure/release-notes.md +++ /dev/null @@ -1,399 +0,0 @@ ---- -Order: 10 -xref: c4b-azure-release-notes -Title: Release Notes -Description: Release Notes for the Chocolatey for Business Azure Environment -OgImage: https://img.chocolatey.org/social-share/release-notes-chocolatey-for-business-azure-environment-og.png -TwitterImage: https://img.chocolatey.org/social-share/release-notes-chocolatey-for-business-azure-environment-twitter.png ---- - -# Chocolatey for Business Azure Environment Release Notes - -> :choco-info: **NOTE** -> -> Issue links may not be publicly available at this time. - -## 0.21.0 (February 8, 2024){#v0.21.0} - -### Breaking Change - -- Trim the list of included Jenkins plugins - see [#103](https://github.com/chocolatey/c4b-azure/issues/103). - -### Improvements - -- Setup Nexus Using NuGet V3 Repositories - see [#145](https://github.com/chocolatey/c4b-azure/issues/145). -- Update to Latest Packages - see [#154](https://github.com/chocolatey/c4b-azure/issues/154). -- Update Jenkins Java Dependency - see [#155](https://github.com/chocolatey/c4b-azure/issues/155). - -### Bundled Version Update - -| Package | Version | -|--------------------------------|---------------| -| chocolatey-agent | 2.1.2 | -| chocolatey-management-database | 0.12.0 | -| chocolatey-management-service | 0.12.0 | -| chocolatey-management-web | 0.12.0 | -| chocolatey.extension | 6.1.2 | -| dotnet-6.0-aspnetruntime | 6.0.26 | -| dotnet-6.0-runtime | 6.0.26 | -| dotnet-aspnetcoremodule-v2 | 16.0.23339 | -| jenkins | 2.426.3 | -| nexus-repository | 3.64.0.4 | -| Temurin11jre | N/A (Removed) | -| Temurin21jre | 21.0.1.1200 (New) | -| vcredist140 | 14.38.33135 | - -## 0.20.0 (August 17, 2023) - -### Improvements - -- Update to Application Gateway v2 - see [#89](https://github.com/chocolatey/c4b-azure/issues/89). -- Accessing Application Gateway Back-end Health Statistics - see [#92](https://github.com/chocolatey/c4b-azure/issues/92). -- Update from Basic Public IP SKU to Standard - see [#108](https://github.com/chocolatey/c4b-azure/issues/108). -- Update to Latest Packages - see [#148](https://github.com/chocolatey/c4b-azure/issues/148). -- Upgrade to AppGateway v2 - see [#149](https://github.com/chocolatey/c4b-azure/pull/149). - -### Bundled Version Update - -| Package | Version | -|----------------------------|---------------| -| chocolatey | 2.2.2 | -| dotnet-6.0-aspnetruntime | 6.0.20 | -| dotnet-6.0-runtime | 6.0.20 | -| dotnet-aspnetcoremodule-v2 | 16.0.23172 | -| jenkins | 2.401.3 | -| nexus-repository | 3.58.1.2 | -| Temurin11jre | 11.0.20.800 | -| Temurinjre | N/A (Removed) | - -## 0.19.0 (July 4, 2023) - -### Feature - -- Update environment deployment to support Chocolatey CLI v2.x - see [#135](https://github.com/chocolatey/c4b-azure/issues/135). - -### Bug Fixes - -- Fix - VM Unable to Start Due to Missing Secret - see [#121](https://github.com/chocolatey/c4b-azure/issues/121). -- Fix - Jenkins Jobs failing when executed with Chocolatey v2.x installed - see [#134](https://github.com/chocolatey/c4b-azure/issues/134). - -### Improvement - -- Update to 2.1.0 and 6.1.0 of Chocolatey products - see [#141](https://github.com/chocolatey/c4b-azure/issues/141). - -### Bundled Version Update - -| Package | Version | -|-------------------------------------|---------------| -| chocolatey | 2.1.0 | -| chocolatey.extension | 6.1.0 | -| chocolatey-agent | 2.1.0 | -| chocolateygui | 2.1.0 | -| chocolateygui.extension | 2.0.0 | -| chocolatey-licensed-jenkins-scripts | 0.1.1 (New) | -| Temurinjre | 20.0.1.900 | -| vcredist140 | 14.36.32532 | - -## 0.18.1 (May 25, 2023) - -### Bug Fix - -- Fix - Updating Jenkins breaks AppGateway Health Checks - see [#126](https://github.com/chocolatey/c4b-azure/issues/126). - -### Improvements - -- Update Chocolatey software components to the latest available versions - see [#128](https://github.com/chocolatey/c4b-azure/issues/128). -- Update ARM Template Resource API Versions - see [#129](https://github.com/chocolatey/c4b-azure/issues/129). -- Update Jenkins Plugins and match selection in C4B Quick Start - see [#131](https://github.com/chocolatey/c4b-azure/issues/131). - -### Bundled Version Update - -| Package | Version | -|-------------------------|---------------| -| chocolatey | 1.4.0 | -| chocolatey.extension | 5.0.3 | -| chocolatey-agent | 1.1.2 | -| chocolateygui | 1.1.3 | -| chocolateygui.extension | 1.0.3 | -| jenkins | 2.387.2 | -| jenkins-set-prefix.hook | 1.0.0 (New) | -| nexus-repository | 3.54.1.01 | -| Temurin11jre | 11.0.19.700 | - -## 0.18.0 (February 21, 2023) - -### Improvement - -- Update Chocolatey software components to the latest available versions - see [#124](https://github.com/chocolatey/c4b-azure/issues/124) - -### Bundled Version Update - -| Package | Version | -|---------------|---------------| -| chocolatey | 1.3.0 | -| chocolateygui | 1.1.1 | - -## 0.17.1 (February 3, 2023) - -### Improvement - -- Update Chocolatey software components to the latest available versions - see [#123](https://github.com/chocolatey/c4b-azure/issues/123) - -### Bundled Version Update - -| Package | Version | -|------------------------------------|---------------| -| chocolatey | 1.2.1 | -| chocolatey-windowsupdate.extension | 1.0.5 | -| chocolatey.extension | 5.0.1 | -| nexus-repository | 3.43.0.01 | -| Temurin11jre | 11.0.18.1000 | -| vcredist140 | 14.32.31332 | - -## 0.17.0 (October 28, 2022) - -### Improvements - -- Update Chocolatey software components to the latest available versions - see [#110](https://github.com/chocolatey/c4b-azure/issues/110) -- Jenkins Job should account for multiple new releases when syncing from test to prod repository - see [#111](https://github.com/chocolatey/c4b-azure/issues/111) - -### Bundled Version Update - -| Package | Version | -|--------------------------------|---------------| -| chocolatey | 1.2.0 | -| chocolatey.extension | 5.0.0 | -| chocolatey-agent | 1.1.1 | -| chocolateygui | 1.1.0 | -| chocolateygui.extension | 1.0.1 | -| chocolatey-management-database | 0.10.1 | -| chocolatey-management-service | 0.10.1 | -| chocolatey-management-web | 0.10.1 | - -## 0.16.0 (September 7, 2022) - -### Improvements - -- Update Chocolatey Central Management to 0.10.0 and include new dependencies - see [#94](https://github.com/chocolatey/c4b-azure/issues/94) -- Update chocolatey.extension to 4.2.0 - see [#99](https://github.com/chocolatey/c4b-azure/issues/99) -- Update chocolatey-agent to 1.1.0 - see [#100](https://github.com/chocolatey/c4b-azure/issues/100) -- Deployment should fail if installation of key components is not successful - see [#101](https://github.com/chocolatey/c4b-azure/issues/101) - -### Bundled Version Update - -| Package | Version | -|--------------------------------|---------------------| -| aspnetcore-runtimepackagestore | N/A (Removed) | -| chocolatey-agent | 1.1.0 | -| chocolatey-management-database | 0.10.0 | -| chocolatey-management-service | 0.10.0 | -| chocolatey-management-web | 0.10.0 | -| chocolatey.extension | 4.2.0 | -| dotnet-6.0-aspnetruntime | 6.0.5 (New) | -| dotnet-6.0-runtime | 6.0.5 (New) | -| dotnet-aspnetcoremodule-v2 | 16.0.22108 (New) | -| dotnetcore-sdk | N/A (Removed) | -| dotnetcore-windowshosting | N/A (Removed) | -| dotnetfx | 4.8.0.20220524 | -| KB2533623 | N/A (Removed) | -| nexus-repository | 3.41.1.01 | -| Temurin11jre | 11.0.16.10100 | -| vcredist140 | 14.28.29913 | -| vcredist2015 | N/A (Removed) | - -## 0.15.0 (May 18, 2022) - -Updates the bundled versions of: - -- [Chocolatey 1.1.0](https://docs.chocolatey.org/en-us/choco/release-notes#march-30-2022) -- [Chocolatey Licensed Extension 4.1.1](https://docs.chocolatey.org/en-us/licensed-extension/release-notes#april-11-2022) -- [Chocolatey Central Management 0.8.0](https://docs.chocolatey.org/en-us/central-management/release-notes#february-28-2022) -- [Chocolatey GUI 1.0.0](https://docs.chocolatey.org/en-us/chocolatey-gui/release-notes#march-21-2022) -- [Chocolatey GUI Licensed Extension 1.0.0](https://docs.chocolatey.org/en-us/chocolatey-gui-licensed-extension/release-notes#march-21-2022) -- [Chocolatey Agent 1.0.0](https://docs.chocolatey.org/en-us/agent/release-notes#march-21-2022) - -### Features - -- Provide easy mechanism for update Certificate - see [#78](https://github.com/chocolatey/c4b-azure/issues/78) - -### Improvements - -- Update to the latest Chocolatey components - see [#77](https://github.com/chocolatey/c4b-azure/issues/77) -- Add Cleanup to Get-UpdatedPackage Jenkins Script - see [#75](https://github.com/chocolatey/c4b-azure/issues/75) -- Packages from the Licensed Feed aren't updated by existing Jenkins Jobs - see [#72](https://github.com/chocolatey/c4b-azure/issues/72) -- Bundled Packages contain x86 and x64 Installers - see [#67](https://github.com/chocolatey/c4b-azure/issues/67) -- Jenkins plugins complain that Jenkins is outdated - see [#65](https://github.com/chocolatey/c4b-azure/issues/65) - -### Documentation - -- Rename repository to match new name - see [#69](https://github.com/chocolatey/c4b-azure/issues/69) -- Allow users to manage their licenses - see [#62](https://github.com/chocolatey/c4b-azure/issues/62) - -### Bundled Version Update - -| Package | Version | -|------------------------------------|--------------------| -| chocolatey | 1.1.0 | -| chocolatey-compatibility.extension | 1.0.0 (new) | -| chocolatey-core.extension | 1.4.0 | -| chocolatey-agent | 1.0.0 | -| chocolatey-extension | 4.1.1 | -| chocolateygui | 1.0.0 | -| chocolateygui.extension | 1.0.0 | -| chocolatey-management-database | 0.8.0 | -| chocolatey-management-service | 0.8.0 | -| chocolatey-management-web | 0.8.0 | -| jenkins | 2.332.3 | -| nexus-repository | 3.38.3.01 | -| Temurinjre | 18.0.1.1000 | -| Temurin11jre | 11.0.15.1000 (new) | -| vcredist140 | 14.32.31326 | - -## 0.14.0 (February 14, 2022) - -Updates the bundled versions of: - -- [Chocolatey 0.12.1](https://docs.chocolatey.org/en-us/choco/release-notes#january-25th-2022) -- [Chocolatey Central Management 0.7.0](https://docs.chocolatey.org/en-us/central-management/release-notes#november-17th-2021) -- [Chocolatey GUI 0.20.0](https://docs.chocolatey.org/en-us/chocolatey-gui/release-notes#february-10-2022). - -### Breaking Changes - -- Internalize Jenkins Plugins - see [#49](https://github.com/chocolatey/c4b-azure/issues/49) - In scenarios where the Jenkins plugins were unavailable to download, the deployment would previously fail. - We have now changed it to contain all of the plugins we require, and to _attempt_ to download the rest. - This may result in an environment that doesn't fail deployment, but is unlike previous successful deployments. - -### Features - -- Upgrades bundled software, as above - see [#60](https://github.com/chocolatey/c4b-azure/issues/60) -- Internalizes packages on first run with the deployed Jenkins job - see [#46](https://github.com/chocolatey/c4b-azure/issues/46) -- Adds commas as a valid separator for Jenkins params - see [#50](https://github.com/chocolatey/c4b-azure/issues/50) -- Adds a HTTP->HTTPS redirect - see [#42](https://github.com/chocolatey/c4b-azure/issues/42) -- Changes the deployed VM size to `B4ms` - see [#55](https://github.com/chocolatey/c4b-azure/issues/55) - -### Bug Fixes - -- Fixes an issue with generated passwords containing quotes - see [#61](https://github.com/chocolatey/c4b-azure/issues/61) -- Deployment now correctly installs internalized version of Chocolatey - see [#59](https://github.com/chocolatey/c4b-azure/issues/59) - -### Bundled Version Update - -| Package | Version | -|------------------------------------|-----------------| -| chocolatey | 0.12.1 | -| chocolatey-agent | 0.12.1 | -| chocolatey-extension | 3.1.0 | -| chocolatey-dotnetfx.extension | 1.0.1 | -| chocolateygui | 0.20.0 | -| chocolateygui.extension | 0.4.0 | -| chocolatey-management-database | 0.7.0 | -| chocolatey-management-service | 0.7.0 | -| chocolatey-management-web | 0.7.0 | -| dotnetcore-sdk | 3.1.410 | -| dotnetfx | 4.8.0.20190930 | -| nexus-repository | 3.37.3.02 | -| Temurinjre | 17.0.1.1200 | -| vcredist140 | 14.30.30708 | -| AdoptOpenJDKjre | N/A (Removed) | -| DotNet4.5.2 | N/A (Removed) | - -## 0.13.2 (September 14, 2021) - -Updates the bundled version of CCM to the [recently released 0.6.2](https://docs.chocolatey.org/en-us/central-management/release-notes#august-26th-2021). - -### Features - -- Upgrades CCM to 0.6.2 - see [#51](https://github.com/chocolatey/c4b-azure/issues/51) - -### Bug Fixes - -- Fixes an issue with package internalization - see [#54](https://github.com/chocolatey/c4b-azure/issues/54) - -### Documentation - -- Adds a guide to enabling RDP [here](https://docs.chocolatey.org/en-us/quick-deployment/azure/rdp) - see [#52](https://github.com/chocolatey/c4b-azure/issues/52) -- Adds a guide for onboarding clients [here](https://docs.chocolatey.org/en-us/quick-deployment/azure/client-setup) - see [#53](https://github.com/chocolatey/c4b-azure/issues/53) - -### Bundled Version Updates - -| Package | Version | -|------------------------------------|-----------------| -| chocolatey-management-database | 0.6.2 | -| chocolatey-management-service | 0.6.2 | -| chocolatey-management-web | 0.6.2 | -| dotnetcore-sdk | 3.1.410 | -| vcredist140 | 14.29.30133 | - -## 0.13.1 (August 13, 2021) - -Update the bundled version of CCM to the [recently released 0.6.1](https://docs.chocolatey.org/en-us/central-management/release-notes#august-5th-2021). - -### Features - -- Updates CCM to version 0.6.1, and updates dependencies -- Validates Chocolatey Licence _before_ deploying resources -- Ensured Chocolatey Agent is installed and checking into the CCM installation - -### Bug Fixes - -- Uses `Restart-WebAppPool` instead of `iisreset`, which fixes a rare issue that failed deployments complaining of insufficient permissions - -### Improvements - -- Changes the available base packages to offer packages not available in the bundles - -### Bundled Version Updates - -| Package | Version | -|------------------------------------|-----------------| -| aspnetcore-runtimepackagestore | 3.1.16 | -| chocolatey-management-database | 0.6.1 | -| chocolatey-management-service | 0.6.1 | -| chocolatey-management-web | 0.6.1 | -| dotnetcore-windowshosting | 3.1.16 | -| vcredist140 | 14.29.30040 | - -## 0.11.5 (July 29, 2021) - -The first released version! Available on the [Azure Marketplace](https://portal.azure.com/#create/chocolateysoftwareinc1605695330527.c4b_azure_qdec4b-qde) from 2021-07-29. - -### Features - -- QDE Deployment via the Azure Marketplace -- Deploys CCM, Nexus, and Jenkins to a VM -- Takes an SSL certificate and FQDN and configures the environment appropriately - -### Documentation - -- Adds basic docs [here](https://docs.chocolatey.org/en-us/quick-deployment/azure/) - -### Bundled Packages - -| Package | Version | -|------------------------------------|---------------------| -| AdoptOpenJDKjre | 16.0.1.900 | -| aspnetcore-runtimepackagestore | 2.2.7 | -| chocolatey | 0.10.15 | -| chocolatey.extension | 2.1.1 | -| chocolatey-agent | 0.11.2 | -| chocolatey-core.extension | 1.3.5.1 | -| chocolateygui | 0.18.1 | -| chocolateygui.extension | 0.2.1 | -| chocolatey-management-database | 0.5.1 | -| chocolatey-management-service | 0.5.1 | -| chocolatey-management-web | 0.5.1 | -| chocolatey-windowsupdate.extension | 1.0.4 | -| DotNet4.5.2 | 4.5.2.20140902 | -| dotnetcore-windowshosting | 2.2.7 | -| jenkins | 2.222.4 | -| KB2533623 | 2.0.0 | -| KB2919355 | 1.0.20160915 | -| KB2919442 | 1.0.20160915 | -| KB2999226 | 1.0.20181019 | -| KB3033929 | 1.0.5 | -| KB3035131 | 1.0.3 | -| KB3063858 | 1.0.0 | -| nexus-repository | 3.31.1.01 | -| vcredist140 | 14.29.30037 | -| vcredist2015 | 14.0.24215.20170201 | diff --git a/input/en-us/c4b-environments/index.md b/input/en-us/c4b-environments/index.md deleted file mode 100644 index 7cd6766d9f..0000000000 --- a/input/en-us/c4b-environments/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 145 -xref: c4b-envs -Title: Chocolatey for Business Environments -Description: Information about supported Chocolatey for Business Environments ---- \ No newline at end of file diff --git a/input/en-us/c4b-environments/quick-start-environment/certificate-renewal.md b/input/en-us/c4b-environments/quick-start-environment/certificate-renewal.md deleted file mode 100644 index f714df806e..0000000000 --- a/input/en-us/c4b-environments/quick-start-environment/certificate-renewal.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -Order: 40 -xref: quick-start-guide-cert-renewal -Title: Certificate Renewal -Description: Certificate renewal docs for Nexus and Chocolatey Central Management -RedirectFrom: en-us/guides/organizations/quick-start-guide/certificate-renewal ---- - -This document is meant to serve as a guide for where to look when needing to renew your SSL certificate(s) for the Nexus and Chocolatey Central Management components of the quick start environment. - -## Set-NexusCert.ps1 - -This script should be saved on your repository server at `C:\choco-setup\scripts\Set-NexusCert.ps1`. - -You can [download the Set-NexusCert.ps1 file directly](https://github.com/chocolatey/choco-quickstart-scripts/blob/main/scripts/Set-NexusCert.ps1), or copy the below code and save it manually. - -```powershell -<# -.SYNOPSIS -Certificate renewal script for Nexus. - -.DESCRIPTION -Helps edit the java keystore file for Nexus when doing a certificate renewal. - -.PARAMETER Thumbprint -Thumbprint value of certificate you want to run Nexus on. Make sure certificate is located at Cert:\LocalMachine\TrustedPeople\ - -.PARAMETER NexusPort -Port you have Nexus configured to run on. - -.EXAMPLE -PS> .\Set-NexusCert.ps1 -Thumbprint 'Your_Certificate_Thumbprint_Value' -NexusPort 'Port_Number' -#> - -[CmdletBinding()] -param( - [Parameter(Mandatory)] - [string] - $Thumbprint, - - [Parameter()] - [string] - $NexusPort = '8443' -) - -begin { - if($host.name -ne 'ConsoleHost') { - Write-Warning "This script cannot be ran from within PowerShell ISE" - Write-Warning "Please launch powershell.exe as an administrator, and run this script again" - break - } -} - -process { - -$ErrorActionPreference = 'Stop' - -if ((Test-Path C:\ProgramData\nexus\etc\ssl\keystore.jks)) { - Remove-Item C:\ProgramData\nexus\etc\ssl\keystore.jks -Force -} - -$KeyTool = "C:\ProgramData\nexus\jre\bin\keytool.exe" -$password = "chocolatey" | ConvertTo-SecureString -AsPlainText -Force -$certificate = Get-ChildItem Cert:\LocalMachine\TrustedPeople\ | Where-Object { $_.Thumbprint -eq $Thumbprint } | Sort-Object | Select-Object -First 1 - -Write-Host "Exporting .pfx file to C:\, will remove when finished" -ForegroundColor Green -$certificate | Export-PfxCertificate -FilePath C:\cert.pfx -Password $password -Get-ChildItem -Path c:\cert.pfx | Import-PfxCertificate -CertStoreLocation Cert:\LocalMachine\My -Exportable -Password $password -Write-Warning -Message "You'll now see prompts and other outputs, things are working as expected, don't do anything" -$string = ("chocolatey" | & $KeyTool -list -v -keystore C:\cert.pfx) -match '^Alias.*' -$currentAlias = ($string -split ':')[1].Trim() - -$passkey = '9hPRGDmfYE3bGyBZCer6AUsh4RTZXbkw' -& $KeyTool -importkeystore -srckeystore C:\cert.pfx -srcstoretype PKCS12 -srcstorepass chocolatey -destkeystore C:\ProgramData\nexus\etc\ssl\keystore.jks -deststoretype JKS -alias $currentAlias -destalias jetty -deststorepass $passkey -& $KeyTool -keypasswd -keystore C:\ProgramData\nexus\etc\ssl\keystore.jks -alias jetty -storepass $passkey -keypass chocolatey -new $passkey - -$xmlPath = 'C:\ProgramData\nexus\etc\jetty\jetty-https.xml' -[xml]$xml = Get-Content -Path 'C:\ProgramData\nexus\etc\jetty\jetty-https.xml' -foreach ($entry in $xml.Configure.New.Where{ $_.id -match 'ssl' }.Set.Where{ $_.name -match 'password' }) { - $entry.InnerText = $passkey -} - -$xml.OuterXml | Set-Content -Path $xmlPath - -Remove-Item C:\cert.pfx - -$nexusPath = 'C:\ProgramData\sonatype-work\nexus3' -$configPath = "$nexusPath\etc\nexus.properties" - -(Get-Content $configPath) | Where-Object {$_ -notmatch "application-port-ssl="} | Set-Content $configPath - -$configStrings = @('jetty.https.stsMaxAge=-1', "application-port-ssl=$NexusPort", 'nexus-args=${jetty.etc}/jetty.xml,${jetty.etc}/jetty-https.xml,${jetty.etc}/jetty-requestlog.xml') -$configStrings | ForEach-Object { - if ((Get-Content -Raw $configPath) -notmatch [regex]::Escape($_)) { - $_ | Add-Content -Path $configPath - } -} - -Restart-Service nexus - -Write-Host -BackgroundColor Black -ForegroundColor DarkGreen "The script has successfully run and the Nexus service is now rebooting for the changes to take effect." -} -``` - -### What does this script do? - -- Prompts for Thumbprint value. This is the certificate thumbprint value you wish to associate to your Nexus instance. -- Optionally you can specify `-Port` with the port number you want Nexus to run over. -- The script will remove your previous keystore.jks file -- Create a new keystore.jks file based on your certificate -- Re-write the nexus.properties file to use the correct port, by default will use port 8443 unless specified in command. -- Restart the Nexus service for changes to take effect and re-load web UI. - -### Script Examples - -```powershell -.\Set-NexusCert.ps1 -Thumbprint 'Your_Certificate_Thumbprint_Value' -NexusPort 'Port_Number' -``` - -```powershell -.\Set-NexusCert.ps1 -Thumbprint 'Your_Certificate_Thumbprint_Value' -``` - -## Set-CCMCert.ps1 - -This script should be saved on your repository server at `C:\choco-setup\scripts\Set-CCMCert.ps1`. - -You can [download the Set-CCMCert.ps1 file directly](https://github.com/chocolatey/choco-quickstart-scripts/blob/main/scripts/Set-CCMCert.ps1), or copy the below code and manually save it. - -```powershell -<# -.SYNOPSIS -Certificate renewal script for Chocolatey Central Management(CCM) - -.DESCRIPTION -This script will go through and renew the certificate association with both the Chocolatey Central Management Service and IIS Web hosted dashboard. - -.PARAMETER CertificateThumbprint -Thumbprint value of the certificate you would like the Chocolatey Central Management Service and Web to run on. -Please make sure the certificate is located in both the Cert:\LocalMachine\TrustedPeople\ and Cert:\LocalMachine\My certificate stores. - -.EXAMPLE -PS> .\Set-CCMCert.ps1 -CertificateThumbprint 'Your_Certificate_Thumbprint_Value' -#> - -[CmdletBinding()] -param( - [Parameter(Mandatory)] - [String] - $CertificateThumbprint -) - -begin { - if($host.name -ne 'ConsoleHost') { - Write-Warning "This script cannot be ran from within PowerShell ISE" - Write-Warning "Please launch powershell.exe as an administrator, and run this script again" - break - } -} - -process { - - #Stop Central Management components - Stop-Service chocolatey-central-management - Get-Process chocolateysoftware.chocolateymanagement.web* | Stop-Process -ErrorAction SilentlyContinue -Force - - #Remove existing bindings - Write-Verbose "Removing existing bindings" - netsh http delete sslcert ipport=0.0.0.0:443 - - #Add new CCM Web IIS Binding - Write-Verbose "Adding new IIS binding to Chocolatey Central Management" - $guid = [Guid]::NewGuid().ToString("B") - netsh http add sslcert ipport=0.0.0.0:443 certhash=$CertificateThumbprint certstorename=MY appid="$guid" - Get-WebBinding -Name ChocolateyCentralManagement | Remove-WebBinding - New-WebBinding -Name ChocolateyCentralManagement -Protocol https -Port 443 -SslFlags 0 -IpAddress '*' - - #Write Thumbprint to CCM Service appsettings.json - $appSettingsJson = 'C:\ProgramData\chocolatey\lib\chocolatey-management-service\tools\service\appsettings.json' - $json = Get-Content $appSettingsJson | ConvertFrom-Json - $json.CertificateThumbprint = $CertificateThumbprint - $json | ConvertTo-Json | Set-Content $appSettingsJson -Force - - #Try Restarting CCM Service - try { - Start-Service chocolatey-central-management -ErrorAction Stop - } - catch { - #Try again... - Start-Service chocolatey-central-management -ErrorAction SilentlyContinue - } - finally { - if ((Get-Service chocolatey-central-management).Status -ne 'Running') { - Write-Warning "Unable to start Chocolatey Central Management service, please start manually in Services.msc" - } - } -} -``` - -### What does this script do? - -- The script will prompt for certificate thumbprint value. Please enter the thumbprint value of the certificate you wish to have the IIS endpoint of Chocolatey Central Management run over. -- Stops the chocolatey-central-management windows service -- Removes any existing binding for the site running over port 443. -- Adds a new IIS binding with the new certificate info. -- Writes the thumbprint value given to the appsettings.json file of the Chocolatey Central Management service to run over. -- Brings up the Chocolatey Central Management service and web components once configured. - -### Script Example - -```powershell -.\Set-CCMCert.ps1 -CertificateThumbprint 'Your_Certificate_Thumbprint_Value' -``` diff --git a/input/en-us/c4b-environments/quick-start-environment/chocolatey-for-business-quick-start-guide.md b/input/en-us/c4b-environments/quick-start-environment/chocolatey-for-business-quick-start-guide.md deleted file mode 100644 index accf440b55..0000000000 --- a/input/en-us/c4b-environments/quick-start-environment/chocolatey-for-business-quick-start-guide.md +++ /dev/null @@ -1,288 +0,0 @@ ---- -Order: 20 -xref: c4b-quick-start-guide -Title: C4B Quick Start Guide -Description: Get up and running quickly with Chocolatey for Business -RedirectFrom: -- docs/chocolatey-for-business-quick-start-guide -- en-us/guides/organizations/quick-start-guide/chocolatey-for-business-quick-start-guide ---- - -Welcome to the Chocolatey for Business (C4B) Quick-Start Guide! This guide will walk you through the basics of configuring a C4B Server on your VM infrastructure of choice. This includes the Chocolatey Licensed components, a NuGet V2 Repository (Nexus), Chocolatey Central Management (CCM), and an Automation Pipeline (Jenkins). - -> :choco-info: **NOTE** -> -> This quick-start guide is intended for customers who have recently purchased Chocolatey for Business (C4B), or are evaluating C4B as part of a proof-of-concept. -> It is **opinionated**, and thus illustrates only one method of setting up your Chocolatey environment. -> Our goal is to get you up-and-running smoothly and efficiently in order to fully test out the feature set. -> For a more exhaustive reference of possible setup scenarios, you may refer to the [Organizational Deployment Documentation](xref:organizational-deployment-guide). - -If you have any questions or would like to discuss more involved implementations, please feel free to reach out to your Chocolatey representative. - -Let's get started! - -## Components - -
-Chocolatey for Business Server Components -

- -As illustrated in the diagram above, there are four main components to a Chocolatey for Business installation: - -1. **C4B Licensed components**: A licensed version of Chocolatey includes: - - Installation of the Chocolatey OSS client package itself (`chocolatey`) - - Chocolatey license file (`chocolatey.license.xml`) installed in the correct directory (`ProgramData\chocolatey\license`) - - Installation of the Chocolatey Licensed extension (`chocolatey.extension`), giving you access to features like Package Builder, Package Internalizer, etc. (full list [here](https://docs.chocolatey.org/en-us/features/)). -

- -1. **NuGet V3 Repository Server App (Nexus)**: Chocolatey works best with a NuGet V3 repository. This application hosts and manages versioning of your Chocolatey package artifacts, in their enhanced NuGet package (.nupkg) file format. The quick start guide helps you setup [Sonatype Nexus Repository Manager (OSS)](https://www.sonatype.com/products/nexus-repository). - -1. **Chocolatey Central Management (CCM)**: CCM is the Web UI portal for your entire Chocolatey environment. Your endpoints check-in to CCM to report their package status. This includes the Chocolatey packages they have installed, and whether any of these packages are outdated. And now, with CCM Deployments, you can also deploy packages or package updates to groups of endpoints, as well as ad-hoc PowerShell commands. CCM is backed by an MS SQL Database. This guide will set up MS SQL Express for you. - -1. **Automation Pipeline (Jenkins)**: A pipeline tool will help you automate repetitive tasks, such checking for updates to a set of Chocolatey Packages from the Chocolatey Community Repository (CCR). If updates exist, the pipeline task will auto-internalize your list of packages, and push them into your NuGet repository for you. This guide will help you set up Jenkins as your automation pipeline. - -## Requirements - -> :choco-danger: **ATTENTION** -> -> The server used for your Chocolatey For Business environment should be a **_fresh, dedicated machine_** that serves no other purpose in your organization. Installation of C4B on a server running mission critical enterprise applications is **NOT** recommended. - -Below are the minimum requirements for setting up your C4B server via this guide: - -- Windows Server 2019+ (ideally, Windows Server 2022) -- 4+ CPU cores (more preferred) -- 16 GB+ RAM (8GB as a bare minimum; 4GB of RAM is reserved specifically for Nexus) -- 500 GB+ of free space for local NuGet package artifact storage (more is better, and you may have to grow this as your packages and versions increase) -- Open outgoing (egress) Internet access -- Administrator user rights - -## Installation - -### Step 0: Preparation of C4B Server - -1. Provision your C4B server on the infrastructure of your choice. - -1. Install all Windows Updates. - -1. If you plan on joining this server to your Active Directory domain, do so now before beginning setup below. - -1. If you plan to use a Purchased/Acquired or Domain SSL certificate, please ensure the CN/Subject value matches the DNS-resolvable Fully Qualified Domain Name (FQDN) of your C4B Server. Place this certificate in the `Local Machine > Personal` certificate store, and ensure that the private key is exportable. - -1. Copy your `chocolatey.license.xml` license file (from the email you received) onto your C4B Server. - -> :choco-warning:**DISCLAIMER**: This guide utilizes code from a GitHub repository, namely: [choco-quickstart-scripts](https://github.com/chocolatey/choco-quickstart-scripts). Though we explain what each script does in drop-down boxes, please do your due diligence to review this code and ensure it meets your Organizational requirements. - -> :memo:**Offline Install**: If your C4B server does not have unrestricted access to the internet, you can download the `choco-quickstart-scripts` repository to a Windows machine that is connected to the internet and run `OfflineInstallPreparation.ps1`. This will use Chocolatey to save all of the required assets into the repository folder, which can then be transferred to the target C4B server. - -### Step 1: Begin C4B Setup - -> :choco-danger: **IMPORTANT** -> -> All commands must be run from an **elevated** Windows PowerShell window (and **not ISE**), by opening your PowerShell console with the `Run as Administrator` option. - -1. Open a Windows PowerShell console with the `Run as Administrator` option, and paste and run the following code: - - ```powershell - Set-ExecutionPolicy Bypass -Scope Process -Force - [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::tls12 - Invoke-RestMethod https://ch0.co/qsg-go | Invoke-Expression - ``` - - >
- > What does this script do? (click to expand) - >
    - >
  • Installs Chocolatey client from https://community.chocolatey.org
    • - >
  • Prompts for your C4B license file location, with validation
    • - >
  • Converts your C4B license into a Chocolatey package
    • - >
  • Configures local "choco-setup" directories
    • - >
  • Downloads setup files from "choco-quickstart-scripts" GitHub repo
    • - >
  • Downloads Chocolatey packages required for setup
    • - >
- >
- -> :memo:**Offline Install**: You can now copy the `C:\choco-setup\` directory to any computer to continue the installation. To zip up that directory, run `Compress-Archive -Path C:\choco-setup\files\* -DestinationPath C:\choco-setup\C4B-Files.zip`. Move the archive to your new machine, and run `Expand-Archive -Path /path/to/C4B-Files.zip -DestinationPath C:\choco-setup\files -Force`. You should then run `Set-Location "$env:SystemDrive\choco-setup\files"; .\Start-C4bSetup.ps1`, and continue with the guide. - -### Step 2: Nexus Setup - -1. In the same **elevated** Windows PowerShell console as above, paste and run the following code: - - ```powershell - Set-Location "$env:SystemDrive\choco-setup\files" - .\Start-C4bNexusSetup.ps1 - ``` - - >
- > What does this script do? (click to expand) - >
    - >
  • Installs Sonatype Nexus Repository Manager OSS instance
    • - >
  • Cleans up all demo repositories on Nexus
    • - >
  • Creates a "ChocolateyInternal" NuGet repository
    • - >
  • Creates a "ChocolateyTest" NuGet repository
    • - >
  • Creates a "choco-install" raw repository
    • - >
  • Sets up "ChocolateyInternal" on C4B Server as source, with API key
    • - >
  • Adds firewall rule for repository access
    • - >
  • Installs MS Edge, and disables first-run experience
    • - >
  • Outputs data to a JSON file to pass between scripts
    • - >
- >
- -### Step 3: Chocolatey Central Management Setup - -1. In the same PowerShell Administrator console as above, paste and run the following code: - - ```powershell - Set-Location "$env:SystemDrive\choco-setup\files" - .\Start-C4bCcmSetup.ps1 - ``` - - >
- > What does this script do? (click to expand) - >
    - >
  • Installs MS SQL Express and SQL Server Management Studio (SSMS)
    • - >
  • Creates "ChocolateyManagement" database, and adds appropriate `ChocoUser` permissions
    • - >
  • Installs all 3 Chocolatey Central Management packages (database, service, web), with correct parameters
    • - >
  • Outputs data to a JSON file to pass between scripts
    • - >
- >
- -### Step 4: Jenkins Setup - -1. In the same **elevated** PowerShell console as above, paste and run the following code: - - ```powershell - Set-Location "$env:SystemDrive\choco-setup\files" - .\Start-C4bJenkinsSetup.ps1 - ``` - - >
- > What does this script do? (click to expand) - >
    - >
  • Installs Jenkins package
    • - >
  • Updates Jenkins plugins
    • - >
  • Configures pre-downloaded Jenkins scripts for Package Internalizer automation
    • - >
  • Sets up pre-defined Jenkins jobs for the scripts above
    • - >
- >
- -### Step 5: SSL Setup - -1. In the same **elevated** PowerShell console as above, paste and run the following code: - - ```powershell - Set-Location "$env:SystemDrive\choco-setup\files" - .\Set-SslSecurity.ps1 - ``` - - **ALTERNATIVE 1 : Custom SSL Certificate** - If you have your own custom SSL certificate (purchased/acquired, or from your Domain CA), you can paste and run the following script with the `Thumbprint` value of your SSL certificate specified: - - ```powershell - Set-Location "$env:SystemDrive\choco-setup\files" - .\Set-SslSecurity.ps1 -Thumbprint '' -Hardened - ``` - - > :choco-warning: **WARNING** - > - > If you are using your own SSL certificate, be sure to place this certificate in the `Local Machine > Personal` certificate store before running the above script, and ensure that the private key is exportable. - - > :choco-info: **NOTE** - > - > You may have noticed the `-Hardened` parameter we've added above. When using a custom SSL certificate, this parameter will further secure access to your C4B Server. A Role and User credential will be configured to limit access to your Nexus repositories. As well, CCM Client and Service Salts are configured to further encrypt your connection between CCM and your endpoint clients. These additional settings are also incorporated into your `Register-C4bEndpoint.ps1` script for onboarding endpoints. We do require you to enable this option if your C4B Server will be Internet-facing, with a FQDN that resolves to a public IP. - - **ALTERNATIVE 2 : Wildcard SSL Certificate** - If you have a wildcard certificate, you will also need to provide a DNS name you wish to use for that certificate: - - ```powershell - Set-Location "$env:SystemDrive\choco-setup\files" - .\Set-SslSecurity.ps1 -Thumbprint '' -CertificateDnsName '' -Hardened - ``` - - For example, with a wildcard certificate with a thumbprint of `deee9b2fabb24bdaae71d82286e08de1` you wish to use `chocolatey.foo.org`, the following would be required: - - ```powershell - Set-Location "$env:SystemDrive\choco-setup\files" - .\Set-SslSecurity.ps1 -Thumbprint deee9b2fabb24bdaae71d82286e08de1 -CertificateDnsName chocolatey.foo.org -Hardened - ``` - -
- - >
- > What does this script do? (click to expand) - >
    - >
  • Adds SSL certificate configuration for Nexus and CCM web portals
    • - >
  • Generates a `Register-C4bEndpoint.ps1` script for you to easily set up endpoint clients
    • - >
  • Outputs data to a JSON file to pass between scripts
    • - >
  • Writes a Readme.html file to the Public Desktop with account information for C4B services
    • - >
  • Auto-opens README, CCM, Nexus, and Jenkins in your web browser
    • - >
  • Removes temporary JSON files used during provisioning
    • - >
- >
- - > :choco-info: **NOTE** - > - > A `Readme.html` file will now be generated on your desktop. This file contains login information for all 3 web portals (CCM, Nexus, and Jenkins). This `Readme.html`, along with all 3 web portals, will automatically be opened in your browser. - -### Step 6: Verification - -1. In the same **elevated** PowerShell console as above, paste and run the following code: - - ```powershell - Set-Location "$env:SystemDrive\choco-setup\files" - .\Start-C4bVerification.ps1 -Fqdn '' - ``` - - If you expect services to be available at `chocoserver.yourcompany.com`, then your command would look like: `.\Start-C4bVerification.ps1 -Fqdn 'chocoserver.yourcompany.com'` - - >
- > What does this script do? (click to expand) - >
    - >
  • Verifies Nexus Repository installation
    • - >
  • Verifies Central Management installation
    • - >
  • Verifies Jenkins installation
    • - >
  • Ensures system firewall is configured
    • - >
  • Ensures Windows Features are installed
    • - >
  • Ensures services are correctly configured
    • - >
  • Ensured README is created
    • - >
- >
- -### Step 7: Setting up Endpoints - -1. Find the `Register-C4bEndpoint.ps1` script in the `choco-setup\files\scripts\` directory on your C4B Server. Copy this script to your client endpoint. - -1. Open an **elevated** PowerShell console on your client endpoint, and browse (`cd`) to the location you copied the script above. Paste and run the following code: - - ```powershell - Set-ExecutionPolicy Bypass -Scope Process -Force - [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::tls12 - .\Register-C4bEndpoint.ps1 - ``` - - >
- > What does this script do? (click to expand) - >
    - >
  • Installs Chocolatey client (chocolatey), using a script from your raw "choco-install" repository
    • - >
  • Runs the "ClientSetup.ps1" script from your raw "choco-install" repository, which does the following:
    • - >
  • Licenses Chocolatey by installing the license package (chocolatey-license) created during QDE setup
    • - >
  • Installs the Chocolatey Licensed Extension (chocolatey.extension) without context menus
    • - >
  • Configures "ChocolateyInternal" source
    • - >
  • Disables access to the "chocolatey" public Chocolatey Community Repository (CCR)
    • - >
  • Configures Self-Service mode and installs Chocolatey GUI (chocolateygui) along with its licensed extension (chocolateygui.extension)
    • - >
  • Configures Central Management (CCM) check-in, and opts endpoints into CCM Deployments
    • - >
- >
- -### Conclusion - -Congratulations! If you followed all the steps detailed above, you should now have a fully functioning Chocolatey for Business implementation deployed in your environment. - -It is worth mentioning that some customers may have a more bespoke environment, with the presence of proxies and additional configuration management applications. Chocolatey is engineered to be quite flexible, specifically to account for these scenarios. Please refer to the many options for installation referenced on the [Installation page](xref:setup-licensed#more-install-options). Again, If you have any questions or would like to discuss more involved implementations, please feel free to reach out to your Chocolatey representative. - -### See it in Action - -If you'd prefer to watch and follow along, here is a recording of our Chocolatey Team going through this guide live on our Twitch stream: - -

-

- -
-
-

diff --git a/input/en-us/c4b-environments/quick-start-environment/firewall-rules.md b/input/en-us/c4b-environments/quick-start-environment/firewall-rules.md deleted file mode 100644 index 7a5ff0ad2f..0000000000 --- a/input/en-us/c4b-environments/quick-start-environment/firewall-rules.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -Order: 25 -xref: firewall-rules -Title: Firewall Rules -Description: Firewall rules used by the Quick Start Environment -RedirectFrom: en-us/c4b-environments/quick-deployment/v1/firewall-changes ---- - -## External Firewall Ports (Optional) - -> :choco-warning: **WARNING** -> -> - Performing this incorrectly could cause security issues and possibly cause you to be subjected to copyright law/redistribution. -> Read all of this first. -> - DO NOT OPEN these ports externally until you have done the following: -> - Locked down your repositories to user/pass access. -> - Updated your ClientSetup script within the raw client repository. - -These are ports that need to be opened through the corporate firewall, if users are **not** on VPN and need to install packages from anywhere. - -| Port | Application | -| :---: | :------------------------- | -| 8443 | Nexus Web UI | -| 24020 | Chocolatey Central Management Service | - -## Internal Firewall Ports - -These are the ports that are already opened on Windows Firewall in the Quick Start Environment. - -| Port | Application | -| :---: | :------------ | -| 8443 | Nexus Web UI | -| 443 | Chocolatey Central Management Dashboard | -| 24020 | Chocolatey Central Management Service | - -> :choco-info: **Cloud Hosting Consideration** -> -> If hosting your Quick Start Environment on a cloud provider, such as Microsoft Azure or Amazon Web Services, be sure to set your inbound networking rules appropriately for the VM. - -## FAQ - -### Can I open up the Chocolatey Central Management Service's port to allow machines to report in from anywhere? - -For best results, we recommend using a VPN connection for client check-ins. -The Chocolatey Central Management service connection is authenticated over SSL, but our best practice recommendation is to secure the connection over a VPN as well. -With Chocolatey Central Management v0.3.0+, more security has been put into allowing for checking in over internet connections. We _highly_ recommend setting both a `centralManagementClientCommunicationSaltAdditivePassword` and `centralManagementServiceCommunicationSaltAdditivePassword` Chocolatey configuration value on your client machines and Chocolatey Central Management Service host machine. diff --git a/input/en-us/c4b-environments/quick-start-environment/index.md b/input/en-us/c4b-environments/quick-start-environment/index.md deleted file mode 100644 index 29d87440ed..0000000000 --- a/input/en-us/c4b-environments/quick-start-environment/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -Order: 30 -xref: quick-start-environment-folder -Title: C4B Quick Start Environment -Description: Quick start environment and supporting documentation -RedirectFrom: en-us/guides/organizations/quick-start-guide ---- \ No newline at end of file diff --git a/input/en-us/c4b-environments/quick-start-environment/qde-deprecation.md b/input/en-us/c4b-environments/quick-start-environment/qde-deprecation.md deleted file mode 100644 index 223d4a589e..0000000000 --- a/input/en-us/c4b-environments/quick-start-environment/qde-deprecation.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -Order: 10 -xref: qde-deprecation -Title: Quick Deploy Environment Deprecation Notice -Description: Landing page for old QDE links -ShowInNavbar: false -ShowInSidebar: false -RedirectFrom: -- en-us/quick-deployment -- en-us/c4b-environments/quick-deployment -- en-us/c4b-environments/quick-deployment/index.html -- en-us/c4b-environments/quick-deployment/release-notes -- en-us/c4b-environments/quick-deployment/setup -- en-us/c4b-environments/quick-deployment/setup/index.html -- en-us/c4b-environments/quick-deployment/setup/desktop-readme -- en-us/c4b-environments/quick-deployment/setup/ssl-setup -- en-us/c4b-environments/quick-deployment/setup/client-setup -- en-us/c4b-environments/quick-deployment/setup/internet-setup -- en-us/c4b-environments/quick-deployment/setup/upgrade-license -- en-us/c4b-environments/quick-deployment/v1 -- en-us/c4b-environments/quick-deployment/v1/index.html -- en-us/c4b-environments/quick-deployment/v1/setup -- en-us/c4b-environments/quick-deployment/v1/desktop-readme -- en-us/c4b-environments/quick-deployment/v1/ssl-setup -- en-us/c4b-environments/quick-deployment/v1/client-setup ---- - -## Why Has the Quick Deploy Environment Been Deprecated - -The Quick Deploy Environment (QDE) solution has been deprecated in favor of our [Chocolatey For Business Quick Start Guide (QSG)](xref:c4b-quick-start-guide) and [Chocolatey For Business Azure Environment](xref:c4b-azure) offerings. The reasoning behind this is the Quick Deploy Environment became too complex and cumbersome to support given the need to build out several different format virtual-machine images to work across the ever-increasing number of Hypervisors being used by our customer base. The Quick Start Guide was created as a solution to this problem. It allows deploying the same components you find in a Quick Deploy Environment, but installing them as PowerShell steps rather than needing to bundle them all as a full Windows Server virtual-machine image. This allows customers to bring their own Windows Server virtual-machine setup into the Hypervisor of their choice. We just simply install the needed components onto the virtual-machine provided. - -The Chocolatey For Business Azure Environment was later developed as our replacement for the Quick Deployment Environment Hyper-V to Azure offering. The Chocolatey For Business Azure Environment is a complete cloud native solution offered through the [Microsoft Azure Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/chocolateysoftwareinc1605695330527.c4b_azure_qde). It stands up the same components of the previous Quick Deploy Environment and current Quick Start Guide solutions using the Azure cloud tooling for the host virtual-machine and networking. - -## I Have a Quick Deploy Environment Solution In Place. What Should I Do Now? - -While we don't support the Quick Deploy Environment as a new deployment option, if already deployed, you have the same components (Sonatype Nexus, Jenkins, and Chocolatey Central Management) as our current environment solutions. You simply need to keep them up-to-date going forward. - -### How Do I Handle SSL Certificate Renewal? - -Our [certificate renewal documentation](xref:quick-start-guide-cert-renewal) for the Quick Start Guide works on the older Quick Deploy Environment. - -### How Do I Upgrade My Sonatype Nexus Instance? - -The same [Sonatype Nexus upgrade documentation](xref:upgrade-nexus) works for the Quick Start Guide and Quick Deploy Environment solutions. - -### How Do I Upgrade Chocolatey Central Management (CCM)? - -See [Chocolatey Central Management Upgrade Documentation](xref:ccm-upgrade). - -### How Do I Upgrade Jenkins? - -See [Jenkins Upgrade Documentation](xref:upgrade-jenkins) diff --git a/input/en-us/c4b-environments/quick-start-environment/upgrade-jenkins.md b/input/en-us/c4b-environments/quick-start-environment/upgrade-jenkins.md deleted file mode 100644 index 69245f1192..0000000000 --- a/input/en-us/c4b-environments/quick-start-environment/upgrade-jenkins.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -Order: 60 -xref: upgrade-jenkins -Title: Upgrading Jenkins -Description: How to upgrade jenkins ---- - -## Upgrade Jenkins in Quick Start Environment - -This document outlines the process for upgrading Jenkins, and it's Java dependency running on your Quick Start Environment. -This guide assumes your server has access to the internet to internalize the needed packages from the Chocolatey community repository. -If your server is internet restricted, please internalize the needed packages on a machine that does have internet access, then push these packages to your internal repository. - -> :choco-warning: **WARNING** -> -> The current Jenkins package requires Java version 17 or 21 which hasn't been added as a package dependency to jenkins (due to the numerous flavours of Java out there). As part of the Quick Start Guide setup we install the temurin21jre package. However any Java version 17 or 21 package will work. -> -> More information is available in the [Java support policy documentation](https://www.jenkins.io/doc/book/platform-information/support-policy-java/). - -## Instructions - -1. Internalize the Jenkins package and push it to your internal repo. -2. Internalize a java package compatible with Jenkins and push it to your internal repo. We recommend the [temurin21jre package](https://community.chocolatey.org/packages/Temurin21jre). -3. Upgrade the temurin21jre and Jenkins packages (Example commands provided below). - -> :choco-info: **Internalizing Note** -> -> You can add the temurin21jre and Jenkins packages to your Jenkins pipelines, setup by the Quick Start Guide, to help keep new versions of these packages in your internal repo. - -### Example Upgrade Commands: - -```powershell -choco upgrade temurin21jre --package-parameters="/ADDLOCAL=FeatureJavaHome" -y --source="'Your Internal Repo'" -``` - -```powershell -choco upgrade jenkins -y --source="'Your Internal Repo'" -``` diff --git a/input/en-us/c4b-environments/quick-start-environment/upgrade-nexus.md b/input/en-us/c4b-environments/quick-start-environment/upgrade-nexus.md deleted file mode 100644 index 0d93d0752e..0000000000 --- a/input/en-us/c4b-environments/quick-start-environment/upgrade-nexus.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -Order: 50 -xref: upgrade-nexus -Title: Upgrading Nexus -Description: How to upgrade nexus -RedirectFrom: en-us/c4b-environments/quick-deployment/setup/upgrade-nexus-qde ---- - -## Upgrade Nexus in Quick Start Environment - -This document outlines the process for upgrading Nexus running inside our Quick Start Environment. -The script provided assumes your server has access to the internet to download the Nexus package from the community repository. -If your server is restricted then internalize the package to your internal repository and update the source in the script appropriately. - -> :choco-warning: **WARNING** -> -> The instructions on this page use parameters available to the nexus-repository package to conserve SSL configuration. If you have arrived here, -> and do not have a Nexus instance configured with SSL, leave off the package parameters. -> -> This command will backup the SSL configuration to the root of your User Profile in a NexusBackup folder. - -## Instructions - -1. Internalize the nexus-repository package and push to your internal repo -2. choco upgrade the nexus-repository package (Example command provided below, which preserves SSL Configuration) - -### Example Upgrade Command: - -> :choco-info: **NOTE** -> -> The following command assumes your nexus instance is available at nexus.example.com. Use your actual FQDN instead - -```powershell -choco upgrade nexus-repository -y --package-parameters="'/Port:8443 /Fqdn:""nexus.example.com"" /BackupSslConfig'" -``` - -> :choco-info: **NOTE** -> ->If you are upgrading from Nexus V 3.22.0.02 or older to a newer version, you may need to make the following change to the jetty-https.xml file. ->Change `class="org.eclipse.jetty.util.ssl.SslContextFactory">` to `class="org.eclipse.jetty.util.ssl.SslContextFactory$Server">` diff --git a/input/en-us/central-management/chococcm/functions/AddCCMGroup.md b/input/en-us/central-management/chococcm/functions/AddCCMGroup.md deleted file mode 100644 index 959dab6236..0000000000 --- a/input/en-us/central-management/chococcm/functions/AddCCMGroup.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -Order: 10 -xref: add-ccmgroup -Title: Add-CCMGroup -Description: Information about the Add-CCMGroup function -RedirectFrom: docs/add-ccmgroup ---- - -# Add-CCMGroup - - - -Adds a group to Central Management - -## Syntax - -~~~powershell -Add-CCMGroup ` - -Name ` - [-Description ] ` - [-Group ] ` - [-Computer ] [] -~~~ - -## Description - -Deployments in Central Management revolve around Groups. Before you can execute a deployment you must define a target group of computers the Deployment will execute on. -Use this function to create new groups in your Central Management system - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Add-CCMGroup -Name PowerShell -Description "I created this via the ChocoCCM module" -Computer pc1,pc2 - -~~~ - -**EXAMPLE 2** - -~~~powershell -Add-CCMGroup -Name PowerShell -Description "I created this via the ChocoCCM module" -Group Webservers - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Name <String> -The name you wish to give the group - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Description [<String>] -A short description of the group - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -Group [<String[]>] -The group(s) to include as members - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### -Computer [<String[]>] -The computer(s) to include as members - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Add-CCMGroup -Full`. diff --git a/input/en-us/central-management/chococcm/functions/AddCCMGroupMember.md b/input/en-us/central-management/chococcm/functions/AddCCMGroupMember.md deleted file mode 100644 index ba2e708072..0000000000 --- a/input/en-us/central-management/chococcm/functions/AddCCMGroupMember.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -Order: 20 -xref: add-ccmgroupmember -Title: Add-CCMGroupMember -Description: Information about the Add-CCMGroupMember function -RedirectFrom: docs/add-ccmgroup-member ---- - -# Add-CCMGroupMember - - - -Adds a member to an existing Group in Central Management - -## Syntax - -~~~powershell -Add-CCMGroupMember ` - [-Name ] ` - [-Group ] [] -~~~ - - -~~~powershell -Add-CCMGroupMember ` - [-Name ] ` - -Computer [] -~~~ - -## Description - -Add new computers and groups to existing Central Management Groups - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Add-CCMGroupMember -Group 'Newly Imaged' -Computer Lab1,Lab2,Lab3 - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Name <String> -The group to edit - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Computer <String[]> -The computer(s) to add - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Group [<String[]>] -The group(s) to add - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Add-CCMGroupMember -Full`. diff --git a/input/en-us/central-management/chococcm/functions/ConnectCCMServer.md b/input/en-us/central-management/chococcm/functions/ConnectCCMServer.md deleted file mode 100644 index 84f21c9f6c..0000000000 --- a/input/en-us/central-management/chococcm/functions/ConnectCCMServer.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -Order: 30 -xref: connect-ccmserver -Title: Connect-CCMServer -Description: Information about the Connect-CCMServer function -RedirectFrom: docs/connect-ccmserver ---- - -# Connect-CCMServer - - - -Creates a session to a central management instance - -## Syntax - -~~~powershell -Connect-CCMServer ` - -Hostname ` - -Credential ` - [-UseSSL] [] -~~~ - -## Description - -Creates a web session cookie used for other functions in the ChocoCCM module - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Connect-CCMServer -Hostname localhost:8090 - -~~~ - -**EXAMPLE 2** - -~~~powershell -$cred = Get-Credential ; Connect-CCMServer -Hostname localhost:8090 -Credential $cred - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Hostname <String> -The hostname and port number of your Central Management installation - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Credential <PSCredential> -The credentials for your Central Management installation. You'll be prompted if left blank - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -UseSSL -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Connect-CCMServer -Full`. - diff --git a/input/en-us/central-management/chococcm/functions/DisableCCMDeployment.md b/input/en-us/central-management/chococcm/functions/DisableCCMDeployment.md deleted file mode 100644 index f8d7da180f..0000000000 --- a/input/en-us/central-management/chococcm/functions/DisableCCMDeployment.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -Order: 40 -xref: disable-ccmdeployment -Title: Disable-CCMDeployment -Description: Information about the Disable-CCMDeployment function -RedirectFrom: docs/disable-ccmdeployment ---- - -# Disable-CCMDeployment - - - -Archive a CCM Deployment. This will move a Deployment to the Archived Deployments section in the Central Management Web UI. - -## Syntax - -~~~powershell -Disable-CCMDeployment ` - [-Deployment ] ` - [-WhatIf] ` - [-Confirm] [] -~~~ - -## Description - -Moves a deployment in Central Management to the archive. This Deployment will no longer be available for use. - - -## Aliases - -`Archive-CCMDeployment` - - -## Examples - - **EXAMPLE 1** - -~~~powershell -Disable-CCMDeployment -Deployment 'Upgrade VLC' - -~~~ - -**EXAMPLE 2** - -~~~powershell -Archive-CCMDeployment -Deployment 'Upgrade VLC' - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Deployment [<String>] -The deployment to archive - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -WhatIf -Property | Value ----------------------- | ----- -Aliases | wi -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Confirm -Property | Value ----------------------- | ----- -Aliases | cf -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Disable-CCMDeployment -Full`. diff --git a/input/en-us/central-management/chococcm/functions/ExportCCMDeployment.md b/input/en-us/central-management/chococcm/functions/ExportCCMDeployment.md deleted file mode 100644 index cc1e710eff..0000000000 --- a/input/en-us/central-management/chococcm/functions/ExportCCMDeployment.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -Order: 50 -xref: export-ccmdeployment -Title: Export-CCMDeployment -Description: Information about the Export-CCMDeployment function -RedirectFrom: docs/export-ccmdeployment ---- - -# Export-CCMDeployment - - - -Exports a Deployment to a CliXML file - -## Syntax - -~~~powershell -Export-CCMDeployment ` - -Deployment ` - [-DeploymentStepsOnly] ` - -OutFile ` - [-AllowClobber] [] -~~~ - -## Description - -Adds ability to export a deployment as cli-xml. Useful for backup/source control of deployments - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Export-CCMDeployment -Deployment TestDeployment -OutFile C:\temp\testdeployment.xml - -~~~ - -**EXAMPLE 2** - -~~~powershell -Export-CCMDeployment -Deployment UpgradeChrome -OutFile C:\temp\upgradechrome_ccmdeployment.xml -AllowClobber - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Deployment <String> -The CCM Deployment to Export - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -DeploymentStepsOnly -Only export a deployment's steps - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -OutFile <String> -The xml file to save the deployment as - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -AllowClobber -Allow a file to be overwritten if it already exists - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Export-CCMDeployment -Full`. diff --git a/input/en-us/central-management/chococcm/functions/ExportCCMDeploymentReport.md b/input/en-us/central-management/chococcm/functions/ExportCCMDeploymentReport.md deleted file mode 100644 index bf9ae53870..0000000000 --- a/input/en-us/central-management/chococcm/functions/ExportCCMDeploymentReport.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -Order: 60 -xref: export-ccmdeploymentreport -Title: Export-CCMDeploymentReport -Description: Information about the Export-CCMDeploymentReport function -RedirectFrom: docs/export-ccmdeployment-report ---- - -# Export-CCMDeploymentReport - - - -Downloads a deployment report from Central Management. This will be saved in the path you specify for OutputFolder - -## Syntax - -~~~powershell -Export-CCMDeploymentReport ` - [-Deployment ] ` - -Type ` - -OutputFolder [] -~~~ - -## Description - -Downloads a deployment report from Central Management in PDF or Excel format. The file is saved to the OutputFolder - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Export-CCMDeploymentReport -Deployment 'Complex' -Type PDF -OutputFolder C:\temp\ - -~~~ - -**EXAMPLE 2** - -~~~powershell -Export-CCMDeploymentReport -Deployment 'Complex -Type Excel -OutputFolder C:\CCMReports - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Deployment [<String>] -The deployment from which to generate and download a report - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Type <String> -The type of report, either PDF or Excel - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -OutputFolder <String> -The path to save the report too - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Export-CCMDeploymentReport -Full`. diff --git a/input/en-us/central-management/chococcm/functions/ExportCCMOutdatedSoftwareReport.md b/input/en-us/central-management/chococcm/functions/ExportCCMOutdatedSoftwareReport.md deleted file mode 100644 index 50bec5518f..0000000000 --- a/input/en-us/central-management/chococcm/functions/ExportCCMOutdatedSoftwareReport.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -Order: 70 -xref: export-ccmoutdatedsoftwarereport -Title: Export-CCMOutdatedSoftwareReport -Description: Information about the Export-CCMOutdatedSoftwareReport function -RedirectFrom: docs/export-ccmoutdated-software-report ---- - -# Export-CCMOutdatedSoftwareReport - - - -Download an outdated Software report from Central Management. This file will be saved to the OutputFolder specified - -## Syntax - -~~~powershell -Export-CCMOutdatedSoftwareReport ` - -Report ` - -Type ` - -OutputFolder [] -~~~ - -## Description - -Download either a PDF or Excel format report of outdated software from Central Management to the OutputFolder specified - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Export-CCMOutdatedSoftwareReport -Report '7/4/2020 6:44:40 PM' -Type PDF -OutputFolder C:\CCMReports - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Report <String> -The report to download - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Type <String> -Specify either PDF or Excel - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -OutputFolder <String> -The path to save the file - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Export-CCMOutdatedSoftwareReport -Full`. - diff --git a/input/en-us/central-management/chococcm/functions/GetCCMComputer.md b/input/en-us/central-management/chococcm/functions/GetCCMComputer.md deleted file mode 100644 index bcd29901d5..0000000000 --- a/input/en-us/central-management/chococcm/functions/GetCCMComputer.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -Order: 80 -xref: get-ccmcomputer -Title: Get-CCMComputer -Description: Information about the Get-CCMComputer function -RedirectFrom: docs/get-ccmcomputer ---- - -# Get-CCMComputer - - - -Returns information about computers in CCM - -## Syntax - -~~~powershell -Get-CCMComputer [] -~~~ - - -~~~powershell -Get-CCMComputer ` - -Computer [] -~~~ - - -~~~powershell -Get-CCMComputer ` - -Id [] -~~~ - -## Description - -Query for all, or by computer name/id to retrieve information about the system as reported in Central Management - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-CCMComputer - -~~~ - -**EXAMPLE 2** - -~~~powershell -Get-CCMComputer -Computer web1 - -~~~ - -**EXAMPLE 3** - -~~~powershell -Get-CCMComputer -Id 13 - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Computer <String[]> -Returns the specified computer(s) - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Id <Int32> -Returns the information for the computer with the specified id - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | 0 -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Get-CCMComputer -Full`. diff --git a/input/en-us/central-management/chococcm/functions/GetCCMDeployment.md b/input/en-us/central-management/chococcm/functions/GetCCMDeployment.md deleted file mode 100644 index dc19f055ff..0000000000 --- a/input/en-us/central-management/chococcm/functions/GetCCMDeployment.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -Order: 90 -xref: get-ccmdeployment -Title: Get-CCMDeployment -Description: Information about the Get-CCMDeployment function -RedirectFrom: docs/get-ccmdeployment ---- - -# Get-CCMDeployment - - - -Return information about a CCM Deployment - -## Syntax - -~~~powershell -Get-CCMDeployment ` - -All [] -~~~ - - -~~~powershell -Get-CCMDeployment ` - -Name [] -~~~ - - -~~~powershell -Get-CCMDeployment ` - -Id [] -~~~ - -## Description - -Returns detailed information about Central Management Deployment Plans - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-CCMDeployment -All - -~~~ - -**EXAMPLE 2** - -~~~powershell -Get-CCMDeployment -Name Bob - -~~~ - -**EXAMPLE 3** - -~~~powershell -Get-CCMDeployment -Id 583 - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -All -Returns all Deployment Plans - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -Name <String> -Returns the named Deployment Plan - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Id <String> -Returns the Deployment Plan with the give Id - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Get-CCMDeployment -Full`. - diff --git a/input/en-us/central-management/chococcm/functions/GetCCMDeploymentStep.md b/input/en-us/central-management/chococcm/functions/GetCCMDeploymentStep.md deleted file mode 100644 index 23e1ccca58..0000000000 --- a/input/en-us/central-management/chococcm/functions/GetCCMDeploymentStep.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -Order: 95 -xref: get-ccmdeploymentstep -Title: Get-CCMDeploymentStep -Description: Information about the Get-CCMDeploymentStep function ---- - -# Get-CCMDeploymentStep - - - -Return information about a CCM Deployment step. - -## Syntax - -~~~powershell -Get-CCMDeploymentStep ` - -InputObject ` - [-IncludeResults] [] -~~~ - -~~~powershell -Get-CCMDeploymentStep ` - -Id ` - [-IncludeResults] [] -~~~ - -## Description - -Returns detailed information about Central Management Deployment Steps. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-CCMDeploymentStep -Id 583 -IncludeResults - -~~~ - -**EXAMPLE 2** - -~~~powershell -Get-CCMDeploymentStep -InputObject $step -IncludeResults - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -InputObject <PSObject> - -Retrieves additional details for the given step. - -Property | Value ----------------------- | -------------- -Aliases | Step -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | true (ByValue) - -### -Id <Int64> - -Returns the Deployment Step with the given Id. - -Property | Value ----------------------- | ------------------------------ -Aliases | DeploymentStepId -Required? | true -Position? | named -Default Value | 0 -Accept Pipeline Input? | true (ByValue, ByPropertyName) - -### -IncludeResults - -If set, additionally retrieves the results for the targeted step. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Get-CCMDeploymentStep -Full`. \ No newline at end of file diff --git a/input/en-us/central-management/chococcm/functions/GetCCMGroup.md b/input/en-us/central-management/chococcm/functions/GetCCMGroup.md deleted file mode 100644 index 3016018e60..0000000000 --- a/input/en-us/central-management/chococcm/functions/GetCCMGroup.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -Order: 100 -xref: get-ccmgroup -Title: Get-CCMGroup -Description: Information about the Get-CCMGroup function -RedirectFrom: docs/get-ccmgroup ---- - -# Get-CCMGroup - - - -Returns group information for your CCM installation - -## Syntax - -~~~powershell -Get-CCMGroup [] -~~~ - - -~~~powershell -Get-CCMGroup ` - -Group [] -~~~ - - -~~~powershell -Get-CCMGroup ` - -Id [] -~~~ - -## Description - -Returns information about the groups created in your CCM Installation - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-CCMGroup - -~~~ - -**EXAMPLE 2** - -~~~powershell -Get-CCMGroup -Id 1 - -~~~ - -**EXAMPLE 3** - -~~~powershell -Get-CCMGroup -Group 'Web Servers' - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Group <String[]> -Returns group with the provided name - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Id <String[]> -Returns group withe the provided id - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Get-CCMGroup -Full`. diff --git a/input/en-us/central-management/chococcm/functions/GetCCMGroupMember.md b/input/en-us/central-management/chococcm/functions/GetCCMGroupMember.md deleted file mode 100644 index 4d5d7b1d1d..0000000000 --- a/input/en-us/central-management/chococcm/functions/GetCCMGroupMember.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -Order: 110 -xref: get-ccmgroupmember -Title: Get-CCMGroupMember -Description: Information about the Get-CCMGroupMember function -RedirectFrom: docs/get-ccmgroup-member ---- - -# Get-CCMGroupMember - - - -Returns information about a CCM group's members - -## Syntax - -~~~powershell -Get-CCMGroupMember ` - -Group [] -~~~ - -## Description - -Return detailed group information from Chocolatey Central Management - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-CCMGroupMember -Group "WebServers" - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Group <String> -The Group to query - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Get-CCMGroupMember -Full`. - diff --git a/input/en-us/central-management/chococcm/functions/GetCCMOutdatedSoftware.md b/input/en-us/central-management/chococcm/functions/GetCCMOutdatedSoftware.md deleted file mode 100644 index 6ae44123ec..0000000000 --- a/input/en-us/central-management/chococcm/functions/GetCCMOutdatedSoftware.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -Order: 120 -xref: get-ccmoutdatedsoftware -Title: Get-CCMOutdatedSoftware -Description: Information about the Get-CCMOutdatedSoftware function -RedirectFrom: docs/get-ccmoutdated-software ---- - -# Get-CCMOutdatedSoftware - - - -Returns all outdated software reported in CCM - -## Syntax - -~~~powershell -Get-CCMOutdatedSoftware [] -~~~ - -## Description - -Returns all outdated software reported in CCM - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-CCMOutdatedSoftware - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Get-CCMOutdatedSoftware -Full`. - diff --git a/input/en-us/central-management/chococcm/functions/GetCCMOutdatedSoftwareMember.md b/input/en-us/central-management/chococcm/functions/GetCCMOutdatedSoftwareMember.md deleted file mode 100644 index a7ab359d6c..0000000000 --- a/input/en-us/central-management/chococcm/functions/GetCCMOutdatedSoftwareMember.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -Order: 130 -xref: get-ccmoutdatedsoftwaremember -Title: Get-CCMOutdatedSoftwareMember -Description: Information about the Get-CCMOutdatedSoftwareMember function -RedirectFrom: docs/get-ccmoutdated-software-member ---- - -# Get-CCMOutdatedSoftwareMember - - - -Returns computers with the requested outdated software. To see outdated software information use Get-CCMOutdatedSoftware - -## Syntax - -~~~powershell -Get-CCMOutdatedSoftwareMember ` - [-Software ] ` - [-Package ] [] -~~~ - -## Description - -Returns the computers with the requested outdated software. To see outdated software information use Get-CCMOutdatedSoftware - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-CCMOutdatedSoftwareMember -Software 'VLC Media Player' - -~~~ - -**EXAMPLE 2** - -~~~powershell -Get-CCMOutdatedSoftwareMember -Package vlc - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Software [<String>] -The software to query. Software here refers to what would show up in Programs and Features on a machine. -Example: If you have VLC installed, this shows as 'VLC Media Player' in Programs and Features. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Package [<String>] -This is the Chocolatey package name to search for. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Get-CCMOutdatedSoftwareMember -Full`. diff --git a/input/en-us/central-management/chococcm/functions/GetCCMOutdatedSoftwareReport.md b/input/en-us/central-management/chococcm/functions/GetCCMOutdatedSoftwareReport.md deleted file mode 100644 index 56a421c1a7..0000000000 --- a/input/en-us/central-management/chococcm/functions/GetCCMOutdatedSoftwareReport.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -Order: 140 -xref: get-ccmoutdatedsoftwarereport -Title: Get-CCMOutdatedSoftwareReport -Description: Information about the Get-CCMOudatedSoftwareReport function -RedirectFrom: docs/get-ccmoutdated-software-report ---- - -# Get-CCMOutdatedSoftwareReport - - - -List all Outdated Software Reports generated in Central Management - -## Syntax - -~~~powershell -Get-CCMOutdatedSoftwareReport [] -~~~ - -## Description - -List all Outdated Software Reports generated in Central Management - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-CCMOutdatedSoftwareReport - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Get-CCMOutdatedSoftwareReport -Full`. diff --git a/input/en-us/central-management/chococcm/functions/GetCCMOutdatedSoftwareReportDetail.md b/input/en-us/central-management/chococcm/functions/GetCCMOutdatedSoftwareReportDetail.md deleted file mode 100644 index 119049e434..0000000000 --- a/input/en-us/central-management/chococcm/functions/GetCCMOutdatedSoftwareReportDetail.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -Order: 150 -xref: get-ccmoutdatedsoftwarereportdetail -Title: Get-CCMOutdatedSoftwareReportDetail -Description: Information about the Get-CCMOutdatedSoftwareReportDetail function -RedirectFrom: docs/get-ccmoutdated-software-report-detail ---- - -# Get-CCMOutdatedSoftwareReportDetail - - - -View detailed information about an Outdated Software Report - -## Syntax - -~~~powershell -Get-CCMOutdatedSoftwareReportDetail ` - -Report [] -~~~ - -## Description - -Return report details from an Outdated Software Report in Central Management - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-CCMOutdatedSoftwareReportDetail -Report '7/4/2020 6:44:40 PM' - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Report <String> -The report to query - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Get-CCMOutdatedSoftwareReportDetail -Full`. diff --git a/input/en-us/central-management/chococcm/functions/GetCCMRole.md b/input/en-us/central-management/chococcm/functions/GetCCMRole.md deleted file mode 100644 index cdf1fd4151..0000000000 --- a/input/en-us/central-management/chococcm/functions/GetCCMRole.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -Order: 160 -xref: get-ccmrole -Title: Get-CCMRole -Description: Information about the Get-CCMRole function -RedirectFrom: docs/get-ccmrole ---- - -# Get-CCMRole - - - -Get roles available in Chococlatey Central Management - -## Syntax - -~~~powershell -Get-CCMRole [] -~~~ - - -~~~powershell -Get-CCMRole ` - [-Name ] [] -~~~ - -## Description - -Return information about roles available in Chocolatey Central Management - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-CCMRole - -~~~ - -**EXAMPLE 2** - -~~~powershell -Get-CCMRole -Name CCMAdmin - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Name [<String>] -The name of a role to query - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Get-CCMRole -Full`. diff --git a/input/en-us/central-management/chococcm/functions/GetCCMSoftware.md b/input/en-us/central-management/chococcm/functions/GetCCMSoftware.md deleted file mode 100644 index 9e12a3fcfb..0000000000 --- a/input/en-us/central-management/chococcm/functions/GetCCMSoftware.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -Order: 170 -xref: get-ccmsoftware -Title: Get-CCMSoftware -Description: Information about the Get-CCMSoftware function -RedirectFrom: docs/get-ccmsoftware ---- - -# Get-CCMSoftware - - - -Returns information about software tracked inside of CCM - -## Syntax - -~~~powershell -Get-CCMSoftware [] -~~~ - - -~~~powershell -Get-CCMSoftware ` - -Software [] -~~~ - - -~~~powershell -Get-CCMSoftware ` - -Package [] -~~~ - - -~~~powershell -Get-CCMSoftware ` - -Id [] -~~~ - -## Description - -Return information about each piece of software managed across all of your estate inside Central Management - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-CCMSoftware - -~~~ - -**EXAMPLE 2** - -~~~powershell -Get-CCMSoftware -Software 'VLC Media Player' - -~~~ - -**EXAMPLE 3** - -~~~powershell -Get-CCMSoftware -Package vlc - -~~~ - -**EXAMPLE 4** - -~~~powershell -Get-CCMSoftware -Id 37 - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Software <String> -Return information about a specific piece of software by friendly name - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Package <String> -Return information about a specific package - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Id <Int32> -Return information about a specific piece of software by id - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | 0 -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Get-CCMSoftware -Full`. diff --git a/input/en-us/central-management/chococcm/functions/GetDeploymentResult.md b/input/en-us/central-management/chococcm/functions/GetDeploymentResult.md deleted file mode 100644 index 591ab4b05f..0000000000 --- a/input/en-us/central-management/chococcm/functions/GetDeploymentResult.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -Order: 180 -xref: get-deploymentresult -Title: Get-DeploymentResult -Description: Information about the Get-DeploymentResult function -RedirectFrom: docs/get-deployment-result ---- - -# Get-DeploymentResult - - - -Return the result of a Central Management Deployment - -## Syntax - -~~~powershell -Get-DeploymentResult ` - -Deployment [] -~~~ - -## Description - -Return the result of a Central Management Deployment - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-CCMDeploymentResult -Name 'Google Chrome Upgrade' - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Deployment <String> -The Deployment for which to return information - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Get-DeploymentResult -Full`. diff --git a/input/en-us/central-management/chococcm/functions/ImportPDQDeployPackage.md b/input/en-us/central-management/chococcm/functions/ImportPDQDeployPackage.md deleted file mode 100644 index 0eed8c64c6..0000000000 --- a/input/en-us/central-management/chococcm/functions/ImportPDQDeployPackage.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -Order: 190 -xref: import-pdqdeploypackage -Title: Import-PDQDeployPackage -Description: Information about the Import-PDQDeployPackage function -RedirectFrom: docs/import-pdqdeploy-package ---- - -# Import-PDQDeployPackage - - - -Imports a PDQ Deploy package as a Central Management Deployment - -## Syntax - -~~~powershell -Import-PDQDeployPackage ` - -PdqXml [] -~~~ - -## Description - -Imports a PDQ Deploy package as a Central Management Deployment - -## Notes - -General notes - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Import-PDQDeployPackage - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -PdqXml <String> -The pdq xml file to import - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Import-PDQDeployPackage -Full`. diff --git a/input/en-us/central-management/chococcm/functions/MoveCCMDeploymentToReady.md b/input/en-us/central-management/chococcm/functions/MoveCCMDeploymentToReady.md deleted file mode 100644 index f7b6e3628a..0000000000 --- a/input/en-us/central-management/chococcm/functions/MoveCCMDeploymentToReady.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -Order: 200 -xref: move-ccmdeploymenttoready -Title: Move-CCMDeploymentToReady -Description: Information about the Move-CCMDeploymentToReady function -RedirectFrom: docs/move-ccmdeployment-to-ready ---- - -# Move-CCMDeploymentToReady - - - -Moves a deployment to Ready state - -## Syntax - -~~~powershell -Move-CCMDeploymentToReady ` - -Deployment [] -~~~ - -## Description - -Moves a Deployment to the Ready state so it can start - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Move-CCMDeploymentToReady -Deployment 'Upgrade Outdated VLC' - -~~~ - -**EXAMPLE 2** - -~~~powershell -Move-CCMDeploymenttoReady -Deployment 'Complex Deployment' - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Deployment <String> -The deployment to move - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Move-CCMDeploymentToReady -Full`. diff --git a/input/en-us/central-management/chococcm/functions/NewCCMDeployment.md b/input/en-us/central-management/chococcm/functions/NewCCMDeployment.md deleted file mode 100644 index d8412069e6..0000000000 --- a/input/en-us/central-management/chococcm/functions/NewCCMDeployment.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -Order: 210 -xref: new-ccmdeployment -Title: New-CCMDeployment -Description: Information about the New-CCMDeployment function -RedirectFrom: docs/new-ccmdeployment ---- - -# New-CCMDeployment - - - -Create a new CCM Deployment Plan - -## Syntax - -~~~powershell -New-CCMDeployment ` - -Name [] -~~~ - -## Description - -Creates a new CCM Deployment. This is just a shell. You'll need to add steps with New-CCMDeploymentStep. - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -New-CCMDeployment -Name 'This is awesome' - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Name <String> -The name for the deployment - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help New-CCMDeployment -Full`. diff --git a/input/en-us/central-management/chococcm/functions/NewCCMDeploymentStep.md b/input/en-us/central-management/chococcm/functions/NewCCMDeploymentStep.md deleted file mode 100644 index ac71bf3f2e..0000000000 --- a/input/en-us/central-management/chococcm/functions/NewCCMDeploymentStep.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -Order: 220 -xref: new-ccmdeploymentstep -Title: New-CCMDeploymentStep -Description: Information about the New-CCMDeploymentStep function -RedirectFrom: docs/new-ccmdeployment-step ---- - -# New-CCMDeploymentStep - - - -Adds a Deployment Step to a Deployment Plan - -## Syntax - -~~~powershell -New-CCMDeploymentStep ` - -Deployment ` - -Name ` - [-TargetGroup ] ` - [-ExecutionTimeoutSeconds ] ` - [-FailOnError] ` - [-RequireSuccessOnAllComputers] ` - [-ValidExitCodes ] ` - -Type ` - -Script [] -~~~ - - -~~~powershell -New-CCMDeploymentStep ` - -Deployment ` - -Name ` - [-TargetGroup ] ` - [-ExecutionTimeoutSeconds ] ` - [-FailOnError] ` - [-RequireSuccessOnAllComputers] ` - [-ValidExitCodes ] ` - -Type ` - -ChocoCommand ` - -PackageName [] -~~~ - - -~~~powershell -New-CCMDeploymentStep ` - -Deployment ` - -Name ` - [-TargetGroup ] ` - [-ExecutionTimeoutSeconds ] ` - [-FailOnError] ` - [-RequireSuccessOnAllComputers] ` - [-ValidExitCodes ] ` - -Type [] -~~~ - -## Description - -Adds both Basic and Advanced steps to a Deployment Plan - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -New-CCMDeploymentStep -Deployment PowerShell -Name 'From ChocoCCM' -TargetGroup WebServers -Type Basic -ChocoCommand upgrade -PackageName firefox - -~~~ - -**EXAMPLE 2** - -~~~powershell -New-CCMDeploymentStep -Deployment PowerShell -Name 'From ChocoCCM' -TargetGroup All,PowerShell -Type Advanced -Script { $process = Get-Process ->> ->> Foreach($p in $process){ ->> Write-Host $p.PID ->> } ->> ->> Write-Host "end" ->> ->> } - -~~~ - -**EXAMPLE 3** - -~~~powershell -New-CCMDeploymentStep -Deployment PowerShell -Name 'From ChocoCCM' -TargetGroup All,PowerShell -Type Advanced -Script {(Get-Content C:\script.txt)} - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Deployment <String> -The Deployment where the step will be added - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Name <String> -The Name of the step - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -TargetGroup [<String[]>] -The group(s) the step will target - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | @() -Accept Pipeline Input? | false - -### -ExecutionTimeoutSeconds [<String>] -How long to wait for the step to timeout. Defaults to 14400 (4 hours) - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | 14400 -Accept Pipeline Input? | false - -### -FailOnError -Fail the step if there is an error. Defaults to True - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | True -Accept Pipeline Input? | false - -### -RequireSuccessOnAllComputers -Ensure all computers are successful before moving to the next step. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -ValidExitCodes [<String[]>] -Valid exit codes your script can emit. Default values are: '0','1605','1614','1641','3010' - -Property | Value ----------------------- | ---------------------------------- -Aliases | -Required? | false -Position? | named -Default Value | @('0','1605','1614','1641','3010') -Accept Pipeline Input? | false - -### -Type <String> -Either a Basic or Advanced Step - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ChocoCommand <String> -Select from Install,Upgrade, or Uninstall. Used with a Simple step type. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -PackageName <String> -The chocolatey package to use with a simple step. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Script <ScriptBlock> -A scriptblock your Advanced step will use - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help New-CCMDeploymentStep -Full`. diff --git a/input/en-us/central-management/chococcm/functions/NewCCMOutdatedSoftwareReport.md b/input/en-us/central-management/chococcm/functions/NewCCMOutdatedSoftwareReport.md deleted file mode 100644 index 317941276a..0000000000 --- a/input/en-us/central-management/chococcm/functions/NewCCMOutdatedSoftwareReport.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -Order: 230 -xref: new-ccmoutdatedsoftwarereport -Title: New-CCMOutdatedSoftwareReport -Description: Information about the New-CCMOutdatedSoftwareReport function -RedirectFrom: docs/new-ccmoutdated-software-report ---- - -# New-CCMOutdatedSoftwareReport - - - -Create a new Outdated Software Report in Central Management - -## Syntax - -~~~powershell -New-CCMOutdatedSoftwareReport [] -~~~ - -## Description - -Create a new Outdated Software Report in Central Management - -## Notes - -Creates a new report named with a creation date timestamp in UTC format - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -New-CCMOutdatedSoftwareReport - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help New-CCMOutdatedSoftwareReport -Full`. diff --git a/input/en-us/central-management/chococcm/functions/RemoveCCMDeployment.md b/input/en-us/central-management/chococcm/functions/RemoveCCMDeployment.md deleted file mode 100644 index ced914276d..0000000000 --- a/input/en-us/central-management/chococcm/functions/RemoveCCMDeployment.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -Order: 240 -xref: remove-ccmdeployment -Title: Remove-CCMDeployment -Description: Information about the Remove-CCMDeployment function -RedirectFrom: docs/remove-ccmdeployment ---- - -# Remove-CCMDeployment - - - -Removes a deployment plan - -## Syntax - -~~~powershell -Remove-CCMDeployment ` - -Deployment ` - [-WhatIf] ` - [-Confirm] [] -~~~ - -## Description - -Removes the Deployment Plan selected from a Central Management installation - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Remove-CCMDeployment -Name 'Super Complex Deployment' - -~~~ - -**EXAMPLE 2** - -~~~powershell -Remove-CCMDeployment -Name 'Deployment Alpha' -Confirm:$false - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Deployment <String[]> -The Deployment to delete - -Property | Value ----------------------- | ------------------------------ -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | true (ByValue, ByPropertyName) - -### -WhatIf -Property | Value ----------------------- | ----- -Aliases | wi -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Confirm -Property | Value ----------------------- | ----- -Aliases | cf -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Remove-CCMDeployment -Full`. diff --git a/input/en-us/central-management/chococcm/functions/RemoveCCMDeploymentStep.md b/input/en-us/central-management/chococcm/functions/RemoveCCMDeploymentStep.md deleted file mode 100644 index 5bcdcd5bee..0000000000 --- a/input/en-us/central-management/chococcm/functions/RemoveCCMDeploymentStep.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -Order: 250 -xref: remove-ccmdeploymentstep -Title: Remove-CCMDeploymentStep -Description: Information about the Remove-CCMDeploymentStep function -RedirectFrom: docs/remove-ccmdeployment-step ---- - -# Remove-CCMDeploymentStep - - - -Removes a deployment plan - -## Syntax - -~~~powershell -Remove-CCMDeploymentStep ` - -Deployment ` - -Step ` - [-WhatIf] ` - [-Confirm] [] -~~~ - -## Description - -Removes the Deployment Plan selected from a Central Management installation - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Remove-CCMDeploymentStep -Name 'Super Complex Deployment' -Step 'Kill web services' - -~~~ - -**EXAMPLE 2** - -~~~powershell -Remove-CCMDeploymentStep -Name 'Deployment Alpha' -Step 'Copy Files' -Confirm:$false - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Deployment <String> -The Deployment to remove a step from - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Step <String> -The Step to remove - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -WhatIf -Property | Value ----------------------- | ----- -Aliases | wi -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Confirm -Property | Value ----------------------- | ----- -Aliases | cf -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Remove-CCMDeploymentStep -Full`. diff --git a/input/en-us/central-management/chococcm/functions/RemoveCCMGroup.md b/input/en-us/central-management/chococcm/functions/RemoveCCMGroup.md deleted file mode 100644 index 0c60145f88..0000000000 --- a/input/en-us/central-management/chococcm/functions/RemoveCCMGroup.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -Order: 260 -xref: remove-ccmgroup -Title: Remove-CCMGroup -Description: Information about the Remove-CCMGroup function -RedirectFrom: docs/remove-ccmgroup ---- - -# Remove-CCMGroup - - - -Removes a CCM group - -## Syntax - -~~~powershell -Remove-CCMGroup ` - [-Group ] ` - [-WhatIf] ` - [-Confirm] [] -~~~ - -## Description - -Removes a group from Chocolatey Central Management - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Remove-CCMGroup -Group WebServers - -~~~ - -**EXAMPLE 2** - -~~~powershell -Remove-CCMGroup -Group WebServer,TestAppDeployment - -~~~ - -**EXAMPLE 3** - -~~~powershell -Remove-CCMGroup -Group PilotPool -Confirm:$false - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Group [<String[]>] -The group(s) to delete - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -WhatIf -Property | Value ----------------------- | ----- -Aliases | wi -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Confirm -Property | Value ----------------------- | ----- -Aliases | cf -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Remove-CCMGroup -Full`. diff --git a/input/en-us/central-management/chococcm/functions/RemoveCCMGroupMember.md b/input/en-us/central-management/chococcm/functions/RemoveCCMGroupMember.md deleted file mode 100644 index 3a745ec522..0000000000 --- a/input/en-us/central-management/chococcm/functions/RemoveCCMGroupMember.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -Order: 270 -xref: remove-ccmgroupmember -Title: Remove-CCMGroupMember -Description: Information about the Remove-CCMGroupMember function -RedirectFrom: docs/remove-ccmgroup-member ---- - -# Remove-CCMGroupMember - - - -Remove a member from a Central Management Group - -## Syntax - -~~~powershell -Remove-CCMGroupMember ` - -Group ` - -Member ` - [-WhatIf] ` - [-Confirm] [] -~~~ - -## Description - -Remove a member from a Central Management Group - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Remove-CCMGroupMember -Group TestLab -Member TestPC1 - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Group <String> -The group you want to remove a member from - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Member <String> -The member you want to remove - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -WhatIf -Property | Value ----------------------- | ----- -Aliases | wi -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Confirm -Property | Value ----------------------- | ----- -Aliases | cf -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Remove-CCMGroupMember -Full`. diff --git a/input/en-us/central-management/chococcm/functions/RemoveCCMStaleDeployment.md b/input/en-us/central-management/chococcm/functions/RemoveCCMStaleDeployment.md deleted file mode 100644 index 9c0af4032c..0000000000 --- a/input/en-us/central-management/chococcm/functions/RemoveCCMStaleDeployment.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -Order: 280 -xref: remove-ccmstaledeployment -Title: Remove-CCMStaleDeployment -Description: Information about the Remove-CCMStaleDeployment function -RedirectFrom: docs/remove-ccmstale-deployment ---- - -# Remove-CCMStaleDeployment - - - -Removes stale CCM Deployments - -## Syntax - -~~~powershell -Remove-CCMStaleDeployment ` - -Age ` - [-WhatIf] ` - [-Confirm] [] -~~~ - -## Description - -Remove stale deployments from CCM based on their age and run status. - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Remove-StaleCCMDeployment -Age 30 - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Age <String> -The age in days to prune - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -WhatIf -Property | Value ----------------------- | ----- -Aliases | wi -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Confirm -Property | Value ----------------------- | ----- -Aliases | cf -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Remove-CCMStaleDeployment -Full`. diff --git a/input/en-us/central-management/chococcm/functions/SetCCMDeploymentStep.md b/input/en-us/central-management/chococcm/functions/SetCCMDeploymentStep.md deleted file mode 100644 index 98732c8a28..0000000000 --- a/input/en-us/central-management/chococcm/functions/SetCCMDeploymentStep.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -Order: 290 -xref: set-ccmdeploymentstep -Title: Set-CCMDeploymentStep -Description: Information about the Set-CCMDeploymentStep function -RedirectFrom: docs/set-ccmdeployment-step ---- - -# Set-CCMDeploymentStep - - - -Modify a Deployment Step of a Central Management Deployment - -## Syntax - -~~~powershell -Set-CCMDeploymentStep ` - -Deployment ` - -Step ` - [-TargetGroup ] ` - [-ExecutionTimeoutSeconds ] ` - [-FailOnError] ` - [-RequireSuccessOnAllComputers] ` - [-ValidExitCodes ] [] -~~~ - - -~~~powershell -Set-CCMDeploymentStep ` - -Deployment ` - -Step ` - [-TargetGroup ] ` - [-ExecutionTimeoutSeconds ] ` - [-FailOnError] ` - [-RequireSuccessOnAllComputers] ` - [-ValidExitCodes ] ` - -ChocoCommand ` - -PackageName [] -~~~ - - -~~~powershell -Set-CCMDeploymentStep ` - -Deployment ` - -Step ` - [-TargetGroup ] ` - [-ExecutionTimeoutSeconds ] ` - [-FailOnError] ` - [-RequireSuccessOnAllComputers] ` - [-ValidExitCodes ] ` - -Script [] -~~~ - -## Description - -Modify a Deployment Step of a Central Management Deployment - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Set-CCMDeploymentStep -Deployment 'Google Chrome Upgrade' -Step 'Upgrade' -TargetGroup LabPCs -ExecutionTimeoutSeconds 14400 -ChocoCommand Upgrade -PackageName googlechrome - -~~~ - -**EXAMPLE 2** - -~~~powershell -$stepParams = @{ - Deployment = 'OS Version' - Step = 'Gather Info' - TargetGroup = 'US-East servers' - Script = { $data = Get-WMIObject win32_OperatingSystem - [pscustomobject]@{ - Name = $data.caption - Version = $data.version - } - } -} -Set-CCMDeploymentStep @stepParams -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Deployment <String> -The Deployment to modify - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Step <String> -The step to modify - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -TargetGroup [<String[]>] -Set the target group of the deployment - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ExecutionTimeoutSeconds [<String>] -Modify the execution timeout of the deployment in seconds - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -FailOnError -Set the FailOnError flag for the deployment step - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -RequireSuccessOnAllComputers -Set the RequreSuccessOnAllComputers for the deployment step - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -ValidExitCodes [<String[]>] -Set valid exit codes for the deployment - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ChocoCommand <String> -For a basic step, set the choco command to execute. Install, Upgrade, or Uninstall - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -PackageName <String> -For a basic step, the choco package to use in the deployment - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Script <ScriptBlock> -For an advanced step, this is a script block of PowerShell code to execute in the step - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Set-CCMDeploymentStep -Full`. diff --git a/input/en-us/central-management/chococcm/functions/SetCCMGroup.md b/input/en-us/central-management/chococcm/functions/SetCCMGroup.md deleted file mode 100644 index 4d6129753f..0000000000 --- a/input/en-us/central-management/chococcm/functions/SetCCMGroup.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -Order: 300 -xref: set-ccmgroup -Title: Set-CCMGroup -Description: Information about the Set-CCMGroup function -RedirectFrom: docs/set-ccmgroup ---- - -# Set-CCMGroup - - - -Change information about a group in Chocolatey Central Management - -## Syntax - -~~~powershell -Set-CCMGroup ` - [-Group ] ` - [-NewName ] ` - [-NewDescription ] [] -~~~ - -## Description - -Change the name or description of a Group in Chocolatey Central Management - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Set-CCMGroup -Group Finance -Description 'Computers in the finance division' - -~~~ - -**EXAMPLE 2** - -~~~powershell -Set-CCMGroup -Group IT -NewName TheBestComputers - -~~~ - -**EXAMPLE 3** - -~~~powershell -Set-CCMGroup -Group Test -NewName NewMachineImaged -Description 'Group for freshly imaged machines needing a baseline package pushed to them' - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Group [<String>] -The Group to edit - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -NewName [<String>] -The new name of the group - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -NewDescription [<String>] -The new description of the group - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Set-CCMGroup -Full`. diff --git a/input/en-us/central-management/chococcm/functions/SetCCMNotificationStatus.md b/input/en-us/central-management/chococcm/functions/SetCCMNotificationStatus.md deleted file mode 100644 index c59c2e1499..0000000000 --- a/input/en-us/central-management/chococcm/functions/SetCCMNotificationStatus.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -Order: 310 -xref: set-ccmnotificationstatus -Title: Set-CCMNotificationStatus -Description: Information about the Set-CCMNotificationStatus function -RedirectFrom: docs/set-ccmnotification-status ---- - -# Set-CCMNotificationStatus - - - -Turn notifications on or off in CCM - -## Syntax - -~~~powershell -Set-CCMNotificationStatus ` - -Enable [] -~~~ - - -~~~powershell -Set-CCMNotificationStatus ` - -Disable [] -~~~ - -## Description - -Manage your notification settings in Central Management. Currently only supports On, or Off - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Set-CCMNotificationStatus -Enable - -~~~ - -**EXAMPLE 2** - -~~~powershell -Set-CCMNotificationStatus -Disable - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Enable -Enables notifications - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -Disable -Disables notifications - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Set-CCMNotificationStatus -Full`. diff --git a/input/en-us/central-management/chococcm/functions/StartCCMDeployment.md b/input/en-us/central-management/chococcm/functions/StartCCMDeployment.md deleted file mode 100644 index a4c52c76a5..0000000000 --- a/input/en-us/central-management/chococcm/functions/StartCCMDeployment.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -Order: 320 -xref: start-ccmdeployment -Title: Start-CCMDeployment -Description: Information about the Start-CCMDeployment function -RedirectFrom: docs/start-ccmdeployment ---- - -# Start-CCMDeployment - - - -Starts a deployment - -## Syntax - -~~~powershell -Start-CCMDeployment ` - -Deployment [] -~~~ - -## Description - -Starts the specified deployment in Central Management - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Start-CCMDeployment -Deployment 'Upgrade Outdated VLC' - -~~~ - -**EXAMPLE 2** - -~~~powershell -Start-CCMDeployment -Deployment 'Complex Deployment' - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Deployment <String> -The deployment to start - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Start-CCMDeployment -Full`. diff --git a/input/en-us/central-management/chococcm/functions/StopCCMDeployment.md b/input/en-us/central-management/chococcm/functions/StopCCMDeployment.md deleted file mode 100644 index 0b3e0794cc..0000000000 --- a/input/en-us/central-management/chococcm/functions/StopCCMDeployment.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -Order: 330 -xref: stop-ccmdeployment -Title: Stop-CCMDeployment -Description: Information about the Stop-CCMDeployment function -RedirectFrom: docs/stop-ccmdeployment ---- - -# Stop-CCMDeployment - - - -Stops a running CCM Deployment - -## Syntax - -~~~powershell -Stop-CCMDeployment ` - [-Deployment ] ` - [-WhatIf] ` - [-Confirm] [] -~~~ - -## Description - -Stops a deployment current running in Central Management - - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Stop-CCMDeployment -Deployment 'Upgrade VLC' - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Deployment [<String>] -The deployment to Stop - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -WhatIf -Property | Value ----------------------- | ----- -Aliases | wi -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Confirm -Property | Value ----------------------- | ----- -Aliases | cf -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` https://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:chococcm-functions) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "ChocoCCM" -Force; Get-Help Stop-CCMDeployment -Full`. diff --git a/input/en-us/central-management/chococcm/functions/index.md b/input/en-us/central-management/chococcm/functions/index.md deleted file mode 100644 index 19562b01f6..0000000000 --- a/input/en-us/central-management/chococcm/functions/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -Order: 30 -xref: chococcm-functions -Title: Functions -Description: All the functions that exist with the ChocoCCM PowerShell Module -RedirectFrom: docs/choco-ccmfunction-reference ---- \ No newline at end of file diff --git a/input/en-us/central-management/chococcm/index.md b/input/en-us/central-management/chococcm/index.md deleted file mode 100644 index 8e8d92192e..0000000000 --- a/input/en-us/central-management/chococcm/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 40 -xref: chococcm -Title: ChocoCCM -Description: This is a PowerShell Modules which contains functions or communicating with the Chocolatey Central Management API ---- \ No newline at end of file diff --git a/input/en-us/central-management/chococcm/release-notes.md b/input/en-us/central-management/chococcm/release-notes.md deleted file mode 100644 index 1ba3ebfe02..0000000000 --- a/input/en-us/central-management/chococcm/release-notes.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -Order: 20 -xref: chococcm-release-notes -Title: Release Notes -Description: Release Notes for ChocoCCM -OgImage: https://img.chocolatey.org/social-share/release-notes-choco-ccm-og.png -TwitterImage: https://img.chocolatey.org/social-share/release-notes-choco-ccm-twitter.png ---- - -# Chocolatey Release Notes - ChocoCCM - -## Summary - -This covers the release notes for the ChocoCCM PowerShell Module, which is available for installation from the [PowerShell Gallery](https://www.powershellgallery.com/packages/ChocoCCM). For more information, installation options, etc, please refer to [ChocoCCM](xref:chococcm). - -> :choco-info: **NOTE** -> -> This PowerShell Module requires an installation of at least CCM v0.4.0 in order to be fully compatible. - -## 0.3.0 (September 8, 2022) - -### Improvement - -- Sign PowerShell Module Files - see [#73](https://github.com/chocolatey/ChocoCCM/issues/73) - -### Documentation - -- Add documentation around building and testing locally - see [#61](https://github.com/chocolatey/ChocoCCM/issues/61) - -## 0.2.0 (April 1, 2021) - -### Bug Fixes - -- Fix - Add-CCMGroup throws `HTTP 400` error -- Fix - Add-CCMGroupMember throws `HTTP 400` error -- Fix - Fetching Deployment Plan by ID fails when Deployment Plan is not in Draft or Ready state -- Fix - Get-CCMGroupMember has incorrect URL -- Fix - Export-CCMDeploymentReport is not exported by the module - -### Improvements - -- Added a new Remove-CCMGroup cmdlet to allow removal of a group -- Added a new Remove-CCMGroupMember cmdlet to allow removal a computer or group from a CCM group -- Added functionally to the Get-CCMDeploymentStep cmdlet to allow retrieval of Deployment Steps, results, and logs from a Deployment Step and its computers - -## 0.1.1 (December 4, 2020) - -### Bug Fixes - -- Fix - New-CCMDeploymentStep Throws HTTP 400 Error -- Fix - Not all functions are returning all objects by default - -## 0.1.0 (November 13, 2020) - -Initial preview release - -### Features - -- PowerShell functions are provided for interacting with the core entities within CCM via the Web API - - Roles - - Groups - - Computers - - Deployments - - Outdated Software - - Reports diff --git a/input/en-us/central-management/chococcm/setup.md b/input/en-us/central-management/chococcm/setup.md deleted file mode 100644 index 4f30915a15..0000000000 --- a/input/en-us/central-management/chococcm/setup.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -Order: 20 -xref: chococcm-setup -Title: Setup -Description: How to setup the ChocoCCM PowerShell Module ---- - -> :choco-info: **NOTE** -> -> The ChocoCCM PowerShell Module requires an installation of at least CCM v0.4.0 in order to be fully compatible. - -## Installation - -To install the ChocoCCM PowerShell Module from the [PowerShell Gallery](https://www.powershellgallery.com/packages/ChocoCCM) use the following command: - -```powershell -Install-Module -Name ChocoCCM -``` - -## Upgrade - -To upgrade to a newer version, when available from the [PowerShell Gallery](https://www.powershellgallery.com/packages/ChocoCCM), run the following command: - -```powershell -Update-Module -Name ChocoCCM -``` - -## Available Functions - -Have a look at the [complete](xref:chococcm-functions) list of all available functions included within the ChocoCCM module. - -Or you can run the following command: - -```powershell -Get-Command -Module ChocoCCM -``` \ No newline at end of file diff --git a/input/en-us/central-management/faq.md b/input/en-us/central-management/faq.md deleted file mode 100644 index ce5518fad4..0000000000 --- a/input/en-us/central-management/faq.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -Order: 50 -xref: ccm-faq -Title: FAQs ---- - -## Timezone FAQs - -### Why Doesn't Chocolatey Central Management Have My Timezone? - -Chocolatey Central Management uses the Windows install of its host to determine if a timezone is valid. If Windows does not know of a timezone, then it will not be made available. - -Some examples of timezones that may not appear: - -* `Qyzylorda Standard Time` does not appear in Windows Server 2016 until you install Windows Update [5031362](https://support.microsoft.com/en-us/topic/october-10-2023-kb5031362-os-build-14393-6351-0c6e713e-3d6a-4593-8a75-af0a605f249c) or later. -* `Yukon Standard Time` does not appear in Windows Server 2016 until you install Windows Update [5031362](https://support.microsoft.com/en-us/topic/october-10-2023-kb5031362-os-build-14393-6351-0c6e713e-3d6a-4593-8a75-af0a605f249c) or later. -* `South Sudan Standard Time` does not appear in Windows Server 2016 until you install [5031362](https://support.microsoft.com/en-us/topic/october-10-2023-kb5031362-os-build-14393-6351-0c6e713e-3d6a-4593-8a75-af0a605f249c) or later. - -### Why Did I Get a Notification That My Chosen Timezone is Invalid? - -Starting in Chocolatey Central Management version 0.12.0, if the chosen timezone is detected to be invalid, we will set it back to the default timezone and alert you through a notification. If you are an Administrator, you may additionally receive a notification that the system timezone was invalid. - -#### User Account Timezone is Invalid - -If you received the below notification, then it means that the timezone used for your user account was invalid, and has been set back to the default system timezone. You can pick your own default by clicking the user menu in the top right and selecting `My Settings`. - - -![Example notification for a user configured timezone being invalid](/assets/images/ccm-manual/notifications/user-timezone-invalid.png) - - -#### System Timezone is Invalid - -If you received the below notification, then it means that the system timezone was invalid, and has been set back to the default of `UTC`. You can adjust the default through the [Settings page](xref:ccm-administration-settings-general). - -![Example notification for a Chocolatey Central Management configured timezone being invalid](/assets/images/ccm-manual/notifications/system-timezone-invalid.png) diff --git a/input/en-us/central-management/index.md b/input/en-us/central-management/index.md deleted file mode 100644 index 3c5aeda0ef..0000000000 --- a/input/en-us/central-management/index.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -Order: 140 -xref: central-management -Title: Chocolatey Central Management (CCM) -Description: What is CCM? -RedirectFrom: docs/central-management ---- - -Chocolatey Central Management (CCM) provides you insights across your desktop and endpoint environments. CCM is available with Chocolatey for Business only. - -Once installed and configured, you can use Chocolatey Central Management to: - -* Bring reporting to the organizational level -* Quickly see all software across the organization and see what needs attention immediately -* Create reports for tracking and auditing purposes -* Manage endpoints with Deployment Plans through groups and collections - -![Central Management Logo](/assets/images/ccm-playwright/account/login/logo.png) - -This provides an overview on Chocolatey Central Management (CCM). It provides both setup and use of CCM. - -## Chocolatey Central Management Components - -The following are all of the Chocolatey components required for Chocolatey Central Management to work. - -* Chocolatey CLI (`chocolatey` package) -* Chocolatey for Business (C4B) Edition. -* Chocolatey Licensed Extension (`chocolatey.extension` package) -* Chocolatey Agent (`chocolatey-agent` package) -* Chocolatey Central Management Database (`chocolatey-management-database` package) - * This deploys the Chocolatey Central Management database schema to a specified SQL Server instance. -* Chocolatey Central Management Service (`chocolatey-management-service` package) - * This installs the Chocolatey Central Management Service, which the Chocolatey Agent will communicate with. -* Chocolatey Central Management Website (`chocolatey-management-web` package) - * This is the Chocolatey Central Management front-end website that is the main user interface of the application. - -### Chocolatey Central Management Component Compatibility Matrix - -Chocolatey Central Management has specific needs that are mostly handled by packaging aspects. As the Chocolatey Agent and Chocolatey Central Management communicate with each other, there are some versions that may not be compatible with each other due to mistakes or fixes that needed to be implemented. This serves as a means of capturing that for you. - -> :choco-info: **NOTE** -> -> Central Management packages (all three) are treated as a singular unit, meaning that they all must be on the same version across one or more machines. Using different versions of Chocolatey Central Management packages is unsupported and will likely not work properly. - -|Chocolatey Central Management|Chocolatey Agent|Chocolatey Licensed Extension|Chocolatey| -|-----------------------------|----------------|-----------------------------|----------| -|0.10.0 |1.1.0+ | 4.2.0+ | 1.1.0+ | -|0.9.0 |1.0.0+ | 4.1.1+ | 1.1.0+ | -|0.8.0 |0.13.0+ | 3.2.0+ | 0.12.0+ | -|0.7.0 |0.11.0+ | 2.1.0+ | 0.10.15+ | -|0.6.x |0.11.0+ | 2.1.0+ | 0.10.15+ | -|0.5.x |0.11.0+ | 2.1.0+ | 0.10.15+ | -|0.4.0 |0.11.0+ | 2.1.0+ | 0.10.15+ | -|0.3.x |0.11.0+ | 2.1.0+ | 0.10.15+ | -|0.2.x |0.10.x | 2.1.0+ | 0.10.15+ | -|0.1.1 |0.9.x | 2.0.3+ | 0.10.15+ | -|0.1.0 |0.9.x | 2.0.0+ | 0.10.12+ | - -## Getting Chocolatey Central Management - -Chocolatey Central Management (CCM) is only available for Chocolatey for Business (C4B) customers. If you are a C4B customer, you can head to the install components section: - -* [Chocolatey Central Management Setup](xref:ccm-setup) -* [Chocolatey Central Management Client Setup](xref:ccm-client) - -If you are not a customer yet, you can [reach out for a trial](https://chocolatey.org/contact/trial). - -> :choco-info: **NOTE** -> -> Trials are limited to organizations. If you are personally wanting to work with CCM and other C4B components, you can purchase a C4B starter pack - see [pricing](https://chocolatey.org/pricing). - -## Stay Up To Date - -* [Chocolatey Central Management Release Notes](xref:ccm-release-notes) -* [Release Announcements Only Mailing List](https://groups.google.com/group/chocolatey-announce) - -## Links - -### Setup / Installation - -* [Chocolatey Central Management Setup](xref:ccm-setup) - * [Chocolatey Central Management Database Setup](xref:ccm-database) - * [Chocolatey Central Management Service Setup](xref:ccm-service) - * [Chocolatey Central Management Web Setup](xref:ccm-website) -* [Chocolatey Central Management Client Setup](xref:ccm-client) - -### Setup / Upgrade - -* [Upgrading Chocolatey Central Management](xref:ccm-upgrade) - -### Using Chocolatey Central Management - -* [Chocolatey Central Management Computers](xref:ccm-computers) -* [Chocolatey Central Management Software](xref:ccm-software) -* [Chocolatey Central Management Groups](xref:ccm-groups) -* [Chocolatey Central Management Deployments](xref:ccm-deployments) -* [Chocolatey Central Management Reports](xref:ccm-reports) - -![Chocolatey Central Management Overview](/assets/images/ccm-manual/screens-mockup.jpg) - -### Chocolatey Central Management API - -* [Chocolatey Central Management API](xref:ccm-api) - -### ChocoCCM Powershell Module - -* [ChocoCCM Module](xref:chococcm) - -## Related Articles - -* [Chocolatey For Business Quick Start Guide(QSG)](xref:c4b-quick-start-guide) -* [Chocolatey For Business Azure Environment](xref:c4b-azure) - -## Roadmap - -* [Chocolatey Central Management Development Roadmap](xref:roadmap#chocolatey-central-management) - -## FAQs - -### How do I take advantage of Chocolatey Central Management? - -You must have a [Business edition of Chocolatey](https://chocolatey.org/compare). Business editions are great for organizations that need to manage the total software lifecycle. - -### I'm a licensed customer, now what? - -See [Getting Chocolatey Central Management](#getting-ccm). - -### Will this become available for lower editions of Chocolatey? - -Chocolatey Central Management will only be available in Chocolatey for Business (C4B). - -### What's the minimum version of the Chocolatey packages I need to use Chocolatey Central Management? - -See [Chocolatey Central Management Component Compatibility Matrix](#chocolatey-central-management-component-compatibility-matrix). - -### Where can I find all the log files for Chocolatey Central Management - -Chocolatey Central Management is made up of a number of components, so there will be a few possible places to find the log files, which you may be asked for when engaging with support. - -* The Chocolatey Central Management Website log file located at `c:\tools\chocolatey-management-web\App_Data\Logs\ccm-website.log`. If you are on a version of CCM prior to 0.2.0, the log will be located at `c:\tools\chocolatey-management-web\App_Data\Logs\Logs.txt`. -* The Chocolatey Central Management service log file is located at `$env:ChocolateyInstall\logs\ccm-service.log`. If you are on a version of CCM prior to 0.2.0, the log will be located at `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\logs\chocolatey.service.host.log`. -* The Chocolatey Agent log file is located at `$env:ChocolateyInstall\logs\chocolatey-agent.log`. If you are on a version of Chocolatey Agent prior to 0.10.0, the log will be located at `$env:ChocolateyInstall\lib\chocolatey-agent\tools\service\logs\chocolatey-agent.log`. - -### Where can I find the changelog or release notes for Chocolatey Central Management? - -Please see [Central Management Release Notes](xref:ccm-release-notes). - -### How do I get support? - -Please run `choco support` from a licensed edition and follow the instructions. - -### How do I set up Chocolatey Central Management? - -* As part of our [Chocolatey for Business Quick Start Guide](xref:c4b-quick-start-guide) -* As part of our [Chocolatey For Business Azure Environment](xref:c4b-azure) -* By following the [Chocolatey Central Management Setup Docs](xref:ccm-setup) - -### If I update the license file, do I need to restart my services and web? - -Yes, you do need to restart the agents, the service, and the web to pick up the license. Here's a handy script: - -```powershell -Get-Service chocolatey-* | Stop-Service -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Get-Service chocolatey-* | Start-Service -``` - -For your agent machines: - -```powershell -Get-Service chocolatey-* | Stop-Service -Get-Service chocolatey-* | Start-Service -``` - -## Common Errors and Resolutions - -### Computers checking in are overwriting each other - -You are generating machines from a base image that already had Chocolatey commercial code on it. This is okay, but you need to remove the Chocolatey Machine Id Guid, which is used to identify a machine as unique. - -When the licensed agent service is installed on a machine, a unique machine id is given to the machine. If you are starting from a template, there is no opportunity for that to be different and when those machines start checking in, they will start overwriting each other. - -Basically you need to go find the machine id at `HKEY_LOCAL_MACHINE\SOFTWARE\Chocolatey\` (`UniqueId`) and remove it as part of your image deployment mechanism. - -```powershell -Write-Host "Removing Chocolatey Unique Machine GUID" -Remove-ItemProperty -Path "HKLM:\Software\Chocolatey" -Name "UniqueId" -Force -# Restart the Agent Service if it is running -``` - -Once you've removed this, you'll need to restart the Agent Service to get it regenerated. - -> :choco-info: **NOTE** -> -> You may **also** need to remove the ChocolateyLocalAdmin user (if you are using it for services) and reinstall the Agent service (and CCM service if on this machine) to get that password corrected. - -### An Internal error occurred during your request - -Check the log files. You may have incorrect database access, but most likely it can come because you didn't follow the steps for setup appropriately. - -### System.Data.SqlClient.SqlException: Invalid column name - -This means you are upgrading things out of order. Please make sure your database is upgraded first, then the service, then the web. diff --git a/input/en-us/central-management/release-notes.md b/input/en-us/central-management/release-notes.md deleted file mode 100644 index 4e846092c7..0000000000 --- a/input/en-us/central-management/release-notes.md +++ /dev/null @@ -1,567 +0,0 @@ ---- -Order: 10 -xref: ccm-release-notes -Title: Release Notes -Description: Release Notes for Chocolatey Central Management -OgImage: https://img.chocolatey.org/social-share/release-notes-chocolatey-central-management-og.png -TwitterImage: https://img.chocolatey.org/social-share/release-notes-chocolatey-central-management-twitter.png -RedirectFrom: docs/release-notes-central-management ---- - -# Chocolatey Release Notes - Chocolatey Central Management - -## Summary - -This covers the release notes for the Chocolatey Central Management (`chocolatey-management-database`, `chocolatey-management-service`, and `chocolatey-management-web`) packages, which covers Central Management server-side functionality. For more information, installation options, etc, please refer to [Chocolatey Central Management](xref:central-management). - -- Installation - [Central Management Setup](xref:ccm-setup) -- Upgrade - [Central Management Upgrade](xref:ccm-upgrade) - -> :choco-info: **NOTE** -> -> This package is available to Chocolatey for Business (C4B) customers only. - -## Other Release Notes - -- Refer to [Open Source Release Notes](xref:floss-release-notes) as commercial editions build on top of open source. -- Chocolatey for Business (C4B) customers - also refer to [Chocolatey Licensed Extension Release Notes](xref:licensed-extension-release-notes) and [Chocolatey Agent Release Notes](xref:agent-release-notes). - -## Known Issues - -- Please see our [GitHub repository issues](https://github.com/chocolatey/chocolatey-licensed-issues/labels/CentralManagement). - -## 0.12.1 (May 23, 2024) - -### Bug Fixes - -- Fix - Duplicated Deployment Step reports created for unreachable and unresponsive computers. - -## 0.12.0 (November 29, 2023) - -Read our [blog post](https://blog.chocolatey.org/2023/11/central-management-0.12.0-released/) about this release. - -### Features - -- Provide ability to create a Deployment Plan for a single outdated package on all affected Computers. -- Provide ability to create a Deployment Plan for all outdated packages on all Computers. -- Provide ability to create an empty Deployment Plan directly for a specific Computer - see [Licensed #259](https://github.com/chocolatey/chocolatey-licensed-issues/issues/259). -- Provide ability to create a Deployment Plan for all outdated packages for a single Computer - see [Licensed #281](https://github.com/chocolatey/chocolatey-licensed-issues/issues/281). -- Provide ability to duplicate an existing Group. -- Provide ability to create an empty Deployment Plan directly for a specific Group. - -### Bug Fixes - -- Fix - The ability to impersonate other users should be removed - see [Licensed #318](https://github.com/chocolatey/chocolatey-licensed-issues/issues/318). -- Fix - Unnecessary permissions should not be present in the `Edit Roles` and `Permissions` modal windows. -- Fix - Notification about a scheduled Deployment Plan failing to start uses incorrect date format. -- Fix - Inconsistent presentation of Export and Action buttons across pages. -- Fix - Missing TimeZone setting for users in Colombia - (UTC - 05:00) Bogota, Lima, Quito, Rio Branco - see [Licensed #356](https://github.com/chocolatey/chocolatey-licensed-issues/issues/356). -- Fix - The HTTP error page of the Chocolatey Central Management Website does not use standard styling. -- Fix - Ensure colors for the "yes/no" badges are consistent on various tables across the website. -- Fix - Encryption Settings information callout is dismissible when it shouldn't be. -- Fix - Password reset link no longer displays an "invalid link" message after updating the Encryption Passphrase. -- Fix - Tables should retain the current page when refreshed automatically. -- Fix - The casing of the word for product "Excel" is incorrect on all export buttons. -- Fix - Names of Deployment Steps can cause an overflow on some modal windows. -- Fix - Action buttons on tables that only contain one option are hidden. -- Fix - Existing configuration stored in the `appsettings.json` file are not respected when upgrading either the Chocolatey Central Management Database or Service packages. -- Fix - Elements on page overlap when a Passphrase is required to be reset by an Admin. - -### Improvements - -- Provide ability to have a Group Details screen. -- Provide ability to automatically fetch updated information for main Deployment Plan page. -- Provide ability to see information about the last refreshed time for Dashboard. -- Provide ability to see the number of Computers that have specific Software installed - see [Licensed #231](https://github.com/chocolatey/chocolatey-licensed-issues/issues/231). -- Provide ability to duplicate a Deployment Step within a Deployment Plan - see [Licensed #332](https://github.com/chocolatey/chocolatey-licensed-issues/issues/332). -- Information about the number of ready/active Deployment Plans is available within the Dashboard page. -- Reporting - Truncate all Excel sheet names to required 31-char limit. -- Use Windows standard naming for all timezones - see [Licensed #325](https://github.com/chocolatey/chocolatey-licensed-issues/issues/325). -- Add an item to the Dashboard page to show the number of Computers that have not recently reported into Chocolatey Central Management. -- Shorten generated names for Deployment Steps to remove redundant "Deployment Step" prefix. - -### Documentation - -- Normalize wording for Deployment Plan and Deployment Step in the user interface. - - -## 0.11.0 (September 18, 2023) - -Read our [blog post](https://blog.chocolatey.org/2023/09/central-management-0.11.0-released/) about this release. - -### Features - -- Add the ability to import and export Deployment Plan definitions. -- Add the ability to export the installed software from a computer to packages.config file - see [Licensed #355](https://github.com/chocolatey/chocolatey-licensed-issues/issues/355). -- Add retention policies for completed and archived Deployment Plans. -- Add computers reporting into Chocolatey Central Management to an 'All Computers' group. -- Add the ability to send email notifications when a Deployment Plan has finished - see [Licensed #328](https://github.com/chocolatey/chocolatey-licensed-issues/issues/328). - -### Bug Fixes - -- Fix - On the Deployment Step Details screen, when showing the contents of the log, the error highlighting doesn't extend to the total available width. -- Fix - When viewing the log for a Deployment Step, the text disappears from the `Copy` button when the mouse is hovered over it. -- Fix - Errors are reported in the Deployment Step Details log when no errors have occurred. -- Fix - Audit log retention does not clean up old log entries - see [Licensed #336](https://github.com/chocolatey/chocolatey-licensed-issues/issues/336). - -### Improvements - -- Add an option to provide a default value for the `executionTimeoutInSeconds` setting, which will be used for all new Deployment Steps. -- Ensure a Computer's `ComputerName` and `FriendlyName` properties are in separate fields when the API returns data. -- Move the `Action` button to the first column in all tables. -- Reinstate the `Return To Deployment Plans` button when editing a Deployment Plan. -- Remove the ability to assign a User the `ChocoAdmin` Role. -- Update email templates for consistency. - -## 0.10.1 (October 6, 2022) - -### Bug Fixes - -- Reporting - Internal error shown when exporting individual software report to excel - see [Licensed #323](https://github.com/chocolatey/chocolatey-licensed-issues/issues/323) -- Deployments - Recurring Deployment Plans are missing Deployment Steps - see [Licensed #322](https://github.com/chocolatey/chocolatey-licensed-issues/issues/322) -- API - GetComputerForView method result missing creationTime - see [Licensed #321](https://github.com/chocolatey/chocolatey-licensed-issues/issues/321) -- Multi-Factor Authentication - Email verification can be enabled while SMTP settings have not been configured -- Website - Ensure builtin accounts' default email addresses are not resolvable - -## 0.10.0 (August 30, 2022) - -### Features - -- Added recurring Deployment Plans. -- Add ability to duplicate an existing Deployment Plan. -- Retention Policies - Automatically delete a computer that hasn't reported in for a configurable period of time. This defaults to 365 days. -- Implement a dark/light mode. -- API - Add a way to query licensed machine count - see [Licensed #272](https://github.com/chocolatey/chocolatey-licensed-issues/issues/272). - -### Bug Fixes - -- Fix - Auditing data may be lost in the database when some entries are updated. - - Editing a Group, Software, or Computer would erase the user who created it and the time it was created. As part of this fix, entries without that information will set the creating user to the user who last modified it. -- Fix - API - Exception when retrieving a Deployment Plan from the `GetDeploymentPlanForView` method. -- Fix - The creation time on the Notifications table was incorrect. -- Fix - Excel and PDF Reports incorrectly show the time in UTC and not the local time zone. -- Fix - Non-administrative users cannot view the Login Attempts section. -- Fix - API - Group statistics were not updated when adding ComputerGroups / GroupGroups via the API. - -### Improvements - -- Computers tab should display Group enrolment - see [Licensed #223](https://github.com/chocolatey/chocolatey-licensed-issues/issues/223). -- Creating a Deployment Plan and then clicking Cancel without adding steps or saving once should remove the Deployment Plan entirely. -- Add the Deployment Plan name to its Step Details pages. -- Add visual indicators that editing/adding/removing Deployment Steps is disabled when the Deployment Plan schedule is outdated. -- Add option of `--version` and `--pre` for a Basic Deployment Step. -- Send email notifications when a scheduled Deployment Plan fails to start. -- Warn when Chocolatey license is due to expire. -- Remember the specified value for Show Entries dropdown on tables. -- Replace loading animation. -- Require new user passwords to be at least 6 characters long. -- Add option for email 2FA as part of authentication - see [Licensed #300](https://github.com/chocolatey/chocolatey-licensed-issues/issues/300). -- Uninstalling chocolatey-management-web should remove IIS Website and Application Pool. -- Add additional auditing fields for Deployments. - -## 0.9.0 (June 15, 2022) - -> :choco-warning: **WARNING** -> -> The dependencies of all the Chocolatey Central Management packages (`chocolatey-management-database`, `chocolatey-management-service`, and `chocolatey-management-web`) have changed in this release. This is to allow the installation of .NET 6.0, which is now a requirement to run Chocolatey Central Management. -> -> In addition to the above, all the Chocolatey Central Management packages now make use of the commercial cmdlets, which means that these packages _have_ to be installed on a correctly licensed machine. [Further information about why we have enabled this can be found on our blog post](https://blog.chocolatey.org/2021/09/chocolatey-licensed-changes-restricted-to-licensed-nodes/) -> -> Finally, support for SQL Server 2008 and SQL Server 2008 R2 has been removed. Any attempt to install one of the Chocolatey Central Management packages against one of these instances will results in an error. [Further information about this change can be found in our blog post](https://blog.chocolatey.org/2022/06/ccm-090-remove-sqlserver2008-support/) - -### Breaking Changes - -- Add support for .NET 6.0 to all Chocolatey Central Management components - - As a result, the dependencies for all of the Chocolatey Central Management packages have changed -- Update all Chocolatey Central Management packages to make use of commercial cmdlets and license validation - - This will mean that installation of the Chocolatey Central Management packages has to happen on a correctly licensed machine. [Further information about why we have enabled this can be found on our blog post](https://blog.chocolatey.org/2021/09/chocolatey-licensed-changes-restricted-to-licensed-nodes/) -- Remove support for SQL Server 2008 - - [Further information about this change can be found in our blog post](https://blog.chocolatey.org/2022/06/ccm-090-remove-sqlserver2008-support/) - -### Features - -- Add ability to update the "Friendly Name" of a computer via the API - see [Licensed #285](https://github.com/chocolatey/chocolatey-licensed-issues/issues/285) -- Provide ability to ensure that all Chocolatey Central Management Chocolatey packages are not being installed to either SQL Server 2008 or SQL Server 2008 R2 instance - -### Bug Fixes - -- Ensure that it is possible to hide links from login page when new user registration is disabled - see [Licensed #270](https://github.com/chocolatey/chocolatey-licensed-issues/issues/270) -- Ensure that no error is caused when viewing a large response from the website -- Ensure that the `chocolatey-management-web` Chocolatey package can be internalized using Package Internalizer - -### Improvements - -- [Security] Remove usage of `morris.js` due to security vulnerability -- Add ability for the CCM Admin Role, by default, to be able to edit a computer - see [Licensed #217](https://github.com/chocolatey/chocolatey-licensed-issues/issues/217) -- Add ability to see the "Friendly Name" assigned to a computer across other areas of Chocolatey Central Management - see [Licensed #221](https://github.com/chocolatey/chocolatey-licensed-issues/issues/221) -- Add colorization to the Deployment Plan / Step screens to show overall result in detail pages -- Remove "Show Log" button from Deployment Step details page for a computer with a result reason of "Unreachable" -- Provide ability to navigate to software screen from the KPI dashboard screen - see [Licensed #282](https://github.com/chocolatey/chocolatey-licensed-issues/issues/282) - -## 0.8.0 (February 28, 2022) - -### Features - -- Ensure that a Deployment Step specifies whether it contains sensitive variables in the script that's to be run. -- Enhanced communication contracts that are used when communicating with Chocolatey Agent. -- Store the database package version number in a database table. - -### Bug Fixes - -- [Security] Fix - ASP.NET Core anti-forgery cookie doesn't use the secure flag. -- Fix - High memory/CPU consumption when there are lots of Computers/Software/Deployment Plans being used. - -### Improvements - -- Disable updating of related group information when it is not needed as computers are reporting in. - -## 0.7.0 (November 17, 2021) - -### Breaking Changes - -- Additional steps required to change LDAP and SMTP passwords. - -The LDAP and SMTP password is no longer present on the page so cannot be inspected. - - We've added an additional step for confirmation of the passwords. -- Encryption passphrase is required. - - To enhance the security of sensitive fields in the database we require the encryption passphrase to be set to a value you provide. - - When any user with the CCM Administrator role logs in they will be redirected to the Settings page where the passphrase can be changed. - - The passphrase change can be deferred but on the 5th login it will be required to set this passphrase before any other changes can be made. - - Users who are not a member of the CCM Administrator role will only be shown a warning that the passphrase needs to be changed and to contact their Administrator to do so. - - The links provided in email activation or password reset emails that were sent prior to the passphrase change will no longer be valid. The user clicking the link will be directed to a page where they can request them again. - -### Improvements - -- Web - Ability to add sensitive variables to advanced PowerShell Deployment Steps - see [documentation](https://docs.chocolatey.org/en-us/central-management/usage/website/sensitive-variables) -- API - Hide token API endpoints from Swagger documentation. -- Web - Update jQuery dependency - see [Licensed #271](https://github.com/chocolatey/chocolatey-licensed-issues/issues/271). - -### Bug Fixes - -- Fix - CCM - Sensitive package parameters shown in database & Deployment Step page - see [Licensed #267](https://github.com/chocolatey/chocolatey-licensed-issues/issues/267). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.6.3 (September 23, 2021) - -### Bug Fixes - -- Fix - Processing of message queue does not complete when an invalid XML file is located - see [Licensed #266](https://github.com/chocolatey/chocolatey-licensed-issues/issues/266) -- Fix - When the "Only one concurrent login per user" setting is enabled, users are locked out of CCM Web UI - see [Licensed #260](https://github.com/chocolatey/chocolatey-licensed-issues/issues/260) -- Fix - Error shown when navigating to certain pages within the CCM Web UI - see [Licensed #262](https://github.com/chocolatey/chocolatey-licensed-issues/issues/262) -- Fix - Users are unable to change IsOutdated status for software entries within CCM Web UI - see [Licensed #264](https://github.com/chocolatey/chocolatey-licensed-issues/issues/264) -- Fix - Users are unable to delete a piece of software within CCM Web UI - see [Licensed #261](https://github.com/chocolatey/chocolatey-licensed-issues/issues/261) -- Fix - Incorrect total number of affected instances within Outdated Software Details Report Details - see [Licensed #265](https://github.com/chocolatey/chocolatey-licensed-issues/issues/265) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.6.2 (August 26, 2021) - -### Bug Fixes - -- Fix - Service - Method to determine correct SSL certificate to use between CCM Service installation script and execution is inconsistent -- Fix - Service - Exceptions thrown during CCM Service startup do not halt internal service tasks -- Fix - Service - CCM Service log file does not contain full error information - see [Licensed #247](https://github.com/chocolatey/chocolatey-licensed-issues/issues/247) -- Fix - Service - Unnecessary/unhelpful log messages are added to the CCM Service log file -- Fix - Web - Upgrading CCM Website package doesn't complete successfully due to locked files -- Fix - Web - Upgrading CCM Website package doesn't ensure creation of required configuration in appsettings.json file -- Fix - Web - Upgrading CCM Website package doesn't ensure creation of required configuration in web.config file -- Fix - Web - Unable to "see" newly created Outdated Software Report when there are greater than 10 reports -- Fix - Web - Incorrect total number of Outdated Software Reports displayed -- Fix - Database - Unable to install 0.6.0/0.6.1 database package when IIS is not installed - see [Licensed #248](https://github.com/chocolatey/chocolatey-licensed-issues/issues/248) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.6.1 (August 5, 2021) - -### Bug Fixes - -- Fix - Service - Unable to install chocolatey-management-service package under certain conditions - see [Licensed #242](https://github.com/chocolatey/chocolatey-licensed-issues/issues/242) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.6.0 (August 3, 2021) - -### Breaking Changes - -- Audit Retention - - By default, Audit Logs generated within CCM will now be kept for 30 days, after which they will be removed - - This can be [changed](https://docs.chocolatey.org/en-us/central-management/setup/website#step-4.5-audit-retention) within the Administration | Settings screen of the CCM Web Application - - If you wish to retain all your current audit logs, we recommend that you back up the AbpAuditLogs table prior to upgrading to this release - -### Improvements - -- All CCM Components have been updated to use .NET Core 3.1 which is supported until [December 2022](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). Previous versions of CCM used NET Core 2.2 which Microsoft ended support for in [December 2019](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) -- Due to this update, the CCM Website now uses the in-process hosting model within IIS. This is enabled by [default starting with ASP.NET Core 3.0](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/in-process-hosting?view=aspnetcore-5.0#enable-in-process-hosting). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.5.1 (April 12, 2021) - -### Bug Fixes - -- Fix - Service - Unable to process Deployment Step report messages that contain invalid XML characters - see [Licensed #216](https://github.com/chocolatey/chocolatey-licensed-issues/issues/216) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.5.0 (March 25, 2021) - -### Breaking Changes - -- Deployments - Provide better resiliency when handling large numbers of computers within a Deployment Plan - see [Licensed #212](https://github.com/chocolatey/chocolatey-licensed-issues/issues/212) - -Previously, while not recommended, the CCM Service could be run as a user with non-administrative rights on the machine, as long as certain permissions were provided to the user. Going forward, there is now a strict requirement that the user that is running the CCM Service has administrative rights on the machine. This is needed to ensure reliability of messages delivered into the CCM Service. - -### Bug Fixes - -- Fix - Web - No data is returned when logged into the website with FIPS compliant checksums enabled on the hosting server - see [Licensed #167](https://github.com/chocolatey/chocolatey-licensed-issues/issues/167) - -### Improvements - -- Installation - CCM Chocolatey Package scripts have been authenticode signed - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.4.0 (November 6, 2020) - -### Breaking Changes - -- Deployments - Machine contact timeout now defaults to infinite (0) to allow for semi-connected environments - -Previously this value was set to a constant value of 20 and not configurable. To revert to previous behaviour, set the machine contact timeout in minutes value for a given Deployment Step to 20. - -### Features - -- Deployment Scheduling - - Scheduled Deployment Plans allows for starting a Deployment Plan at some point in the future - - Maintenance Windows - Ability to specify date and time for when no more computers within a Deployment Step can start -- API - Swagger UI allows visualization and interaction with all CCM API operations - see [Licensed #183](https://github.com/chocolatey/chocolatey-licensed-issues/issues/183) -- Long Running Deployments - Enables support for semi-connected computers - -### Bug Fixes - -- Fix - Deployments - Computers marked unreachable should not be picked up in future steps in same Deployment Plan -- Fix - Deployments - Adding distinct groups that share computers to a Deployment Plan results in duplicated computers within Deployment Steps -- Fix - Web - Authentication of external user (i.e. LDAP) fails when no email address is configured for user - see [Licensed #181](https://github.com/chocolatey/chocolatey-licensed-issues/issues/181) -- Fix - Database - Unable to upgrade database when user specific permissions (i.e. instead of assigning a role to a user) for CCM are used for any user -- Fix - Deployments - Execution timeout of infinite (0) for a Deployment Step is not being respected when querying for timed out computers -- Fix - Deployments - Machine contact timeout for Deployment Step is not being respected, Deployment Step incorrectly wait indefinitely (due to changes in v0.3.1) -- Fix - Web - Real time notifications never reach CCM Web UI -- Fix - Web - Notifications page has no way to see entire notification - -### Improvements - -- Deployments - Handle Deployment Step activation order properly when the same computer is in multiple Deployment Plans that are active at the same time -- Service - Configuration - Provide clarity in log messages when salt additive configuration values are misconfigured -- Deployments - Round percentage complete values on report pages while Deployment Step is in progress -- Deployments - Auto-refresh Deployment Plan report pages - -## 0.3.1 (October 5, 2020) - -### Bug FIxes - -- Fix - Database - Upgrade fails when passing database parameters due to incorrect cmdlet name - see [Licensed #161](https://github.com/chocolatey/chocolatey-licensed-issues/issues/161) -- Fix - Service Install - Ensure that existing certificate is located in TrustedPeople certificate store -- Fix - Service Install - Netsh Entries Incorrectly Parsed ("Cannot index into a null array") when installing in different locales - see [Licensed #174](https://github.com/chocolatey/chocolatey-licensed-issues/issues/174) -- Fix - Web - Invalid LDAP credentials/URL should not prevent login for ccmadmin user -- Fix - Deployments - Start Date Time for Deployment Step is overwritten when Step is marked as inconclusive -- Fix - Deployments - Switching from Basic to Advanced script without providing package name causes validation errors - see [Licensed #164](https://github.com/chocolatey/chocolatey-licensed-issues/issues/164) - -### Improvements - -- Service Install - Allow skipping certificate binding with package parameter /SkipCertificateBinding -- Include CreationTime property on Deployment Plan entity - useful when querying via CCM API -- Web - Deployments UI - Add Deployment Step modal window should default to basic view - -## 0.3.0 (June 25, 2020) - -### Breaking Changes - -- Chocolatey Central Management v0.3.0 will only work with Chocolatey Agent v0.11.0+. Upgrade order doesn't matter as you'll need to be on CCM v0.3.0 and Agent v0.11.0 before things start working again. See https://docs.chocolatey.org/en-us/central-management/#ccm-component-compatibility-matrix. - -### Bug Fixes - -- Fix - Service - Communication with Chocolatey Agent fails on Incorrect Passphrase - see [Licensed #152](https://github.com/chocolatey/chocolatey-licensed-issues/issues/152) -- Fix - Web - Do not recreate website w/bindings on upgrade - see [Licensed #156](https://github.com/chocolatey/chocolatey-licensed-issues/issues/156) - -## 0.2.0 (June 18, 2020) - -Deployments Release - we are excited to bring about managing remote machines with [Central Management Deployments](https://blog.chocolatey.org/2020/05/announcing-deployments/) coming in this release! There are quite a few things we've brought into the initial release and we think you'll agree that it is a powerful, yet easy to use interface. Read [the announcement.](https://blog.chocolatey.org/2020/05/announcing-deployments/). We've also overhauled the documentation to make it understandable and approachable. Please see https://docs.chocolatey.org/en-us/central-management/. - -> :choco-info: **NOTE** -> -> Log locations have changed. Please see [Central Management FAQs](xref:central-management#faqs) for more information. - -### Features - -- [Central Management Deployments](https://blog.chocolatey.org/2020/05/announcing-deployments/): - - Create target groups to deploy to - - Create a Deployment Plan with one or more Steps - - Each step can target multiple groups, and different groups in each step if desired - - Script a Chocolatey package - - With additional permissions, run a full PowerShell script instead - - Choose how failures in each step are handled - - Reorder steps - - Control permissions on who can deploy Chocolatey packages and who can run full scripts - - See progress on active Deployment Plans - - View logs for computers that executed a Deployment Step - - Report on completed Deployment Plans including exporting to PDF for sharing with executive staff - -### Bug Fixes - -- [Security] Fix - Framework does not encrypt LDAP Password in the database - see [licensed #144](https://github.com/chocolatey/chocolatey-licensed-issues/issues/144) -- Fix - Service - Error on installation when providing existing certificate: Cannot index into a null array - see [licensed #143](https://github.com/chocolatey/chocolatey-licensed-issues/issues/143) -- Fix - Web - Do not enable recaptcha by default for site registration - see [licensed #128](https://github.com/chocolatey/chocolatey-licensed-issues/issues/128) -- Fix - Web - Create/Edit Computer and Software modals are not saving changes - see [licensed #125](https://github.com/chocolatey/chocolatey-licensed-issues/issues/125) -- Fix - Web - Remove default permission to edit software and computers -- Fix - Web - Restrict What Can Be Created or Edited For Computers and Software -- Fix - Web - Deleted/Hidden items are still being used for counts for paging purposes in Software -- Fix - Web - The license count looks clickable at times when it is not clickable -- Fix - Web - After installation of CCM, doing an iisreset breaks the site -- Fix - All - Monitoring chocolatey.config for changes could potentially lock the file from being written to by choco -- Fix - All - Logging - CCM service not responding to calls and stops logging after choco configuration file is edited -- Fix - Service - Changing CentralManagementServiceUrl value in chocolatey.config causes running management service to crash - -### Improvements - -- Web - Allow removing computers as a default permission for ccmadmin role - see [licensed #133](https://github.com/chocolatey/chocolatey-licensed-issues/issues/133) -- Service - On install/upgrade, write out the FQDN and link to provide to chocolatey agents -- Logging - Service and DB Migrator should log to the root logs folder of Chocolatey Installation -- All - Logging - Adjust format to match closer with other Chocolatey log file formats -- Service - Set higher encryption when available (TLS 1.2) -- Database Install - Add `/SkipDatabasePermissionCheck` parameter to skip permissions check - see [licensed #147](https://github.com/chocolatey/chocolatey-licensed-issues/issues/147) -- Trial licenses that do not include counts will allow 100 licenses - see [licensed #140](https://github.com/chocolatey/chocolatey-licensed-issues/issues/140) - -## 0.1.1 (January 30, 2020) - -### Bug Fixes - -- [Security] Fix - Database - Don't emit Connection String information to log file -- [Security] Fix - Web - Add missing ability to use Active Directory (LDAP) for authentication -- Fix - Web - Error on installation 'HTTP Error 500.21 - Internal Server Error Handler "aspNetCore" has a bad module "AspNetCoreModule" in its module list' - see [Licensed #114](https://github.com/chocolatey/chocolatey-licensed-issues/issues/114) -- Fix - Service - Unable to parse netsh entries that contain hostname:port bindings - see [Licensed #96](https://github.com/chocolatey/chocolatey-licensed-issues/issues/96) -- Fix - Web - When setting SMTP configuration the SSL checkbox status is being ignored - see [Licensed #87](https://github.com/chocolatey/chocolatey-licensed-issues/issues/87) -- Fix - Service - "The remote server returned an unexpected response: (413) Request Entity Too Large." - see [Licensed #95](https://github.com/chocolatey/chocolatey-licensed-issues/issues/95) -- Fix - Service - Unable to install CCM service with less than PowerShell v5 due to error on New-Guid cmdlet -- Fix - Web - Time discrepancy between Computers and Computer details - see [Licensed #97](https://github.com/chocolatey/chocolatey-licensed-issues/issues/97) -- Fix - Web - Remove ability to brand sections of CCM for now as it wasn't meant to be there yet and doesn't work -- Fix - Service - Unable to uninstall chocolatey-management-service due to incorrect name in package uninstall script -- Fix - Web - License count information is not being displayed correctly (e.g. 90 / n/a) - see [Licensed #80](https://github.com/chocolatey/chocolatey-licensed-issues/issues/80) -- Fix - Service - IP Address of Computer is not updating - see [Licensed #86](https://github.com/chocolatey/chocolatey-licensed-issues/issues/86) -- Fix - Web - Unable to upload a profile picture for user -- Fix - Web - Hovering over tooltips in Internet Explorer causes the page to jump -- Fix - Web - Clicking the Chocolatey icon in top left-hand corner opens new tab -- Fix - Web - Website Logs are not appearing the in Maintenance Tab -- Fix - All - Move from DEBUG level reporting by default to INFO level reporting to reduce amount of logging -- Fix - Web - Improve wording in email templates and ensure consistent naming is used - -### Improvements - -- Database - Check whether provided SQL Server connection string actually works prior to starting installation -- Web - Optimize/Reduce Size of Chocolatey package by removing unnecessary files - see [Licensed #62](https://github.com/chocolatey/chocolatey-licensed-issues/issues/62) -- All - Show a warning when no package parameters are passed when initially installing CCM packages -- All - Show a warning during installation when provided SQL Server connection string doesn't provide an explicit user/password to connect with -- Service - Adjust logs to provide more appropriate information for normal operations -- Web - Autofocus on new password text box on password change screen - -## 0.1.0 (May 22, 2019) - -Initial preview release - -### Features - -- Reports - Ability to view and generate report (Excel/PDF) for all currently outdated software -- Dashboard - Provide a dashboard screen with key KPI values -- Overview - Show number of machines checking into CCM and compare to number currently licensed - -### Bug Fixes - -- Fix - Packaging - Before upgrading Web Package ensure that dotnet process isn't running -- Fix - Web Site - Ensure that minified versions of all assets are used -- Fix - Web Site - Ensure consistent Date/Time Formatting used everywhere -- Fix - Web Site - Corrected duplicate display of search input box on some screens -- Fix - Web Site - Error when attempting to sort by any column in table on Computer Details screen -- Fix - Web Site - Error when attempting to sort by Name or Package Title column in table on Software screen -- Fix - Web Site - Tab does not sort by outdated first on Software screen -- Fix - Web Site - Timezone modification doesn't provide useful information to user -- Fix - Web Site - Only show Software that is installed on at least one machine -- Fix - Web Site - Excel Export generates errors when DateTime values are included -- Fix - Versioning - Ensure correct version number is stamped on all generated assemblies -- Fix - Service - Correct usage of default port number, which should be 24020 -- Fix - Service - New-SelfSignedCertificate usage doesn't work on earlier PowerShell versions -- Fix - Service - Ensure correct error handling for incorrect/missing SQL Server credentials -- Fix - Database - Ensure SQL Server 2008 support -- Fix - Database - Migrator doesn't exit with non-zero exit code when there is an error -- Fix - Installation - Ensure usage of FQDN for all components - -### Improvements - -- Logging - Provided better logging during Service Certificate installation -- Installation - Verify and usage persisted appsettings.json file during upgrade -- Installation - Reduce issues unpacking web package by shortening paths in packaging -- Uninstallation - Remove modifications that were done as part of installation -- Database - Don't attempt to seed database tables every time application starts -- Packaging - Removed unnecessary files from package, making it much smaller -- Packaging - Added required dependencies to packages -- Packaging - Add information about available installation parameters to package description -- Service - Allow modification of configuration settings without the need to restart Windows Service - -## 0.1.0-beta-20181009 (October 9, 2018) - -### Features - -- [Security] Installation - Provide encryption for all persisted configuration data -- [Security] Installation - Sign all PowerShell Scripts and assemblies shipped as part of release -- [Security] Web Site - Provide full RBAC to site and API -- Audit - Provide ability to list all computers that are currently in use across environment -- Audit - Provide ability to list all software that is currently installed across environment -- Reports - Ability to view and generate report (Excel/PDF) for all currently installed software -- Reports - Ability to view and generate report (Excel/PDF) for all computers currently in use diff --git a/input/en-us/central-management/setup/client.md b/input/en-us/central-management/setup/client.md deleted file mode 100644 index 12eba525d8..0000000000 --- a/input/en-us/central-management/setup/client.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -Order: 40 -xref: ccm-client -Title: Client -Description: How to setup client machines to report into CCM -RedirectFrom: docs/central-management-setup-client ---- - -This will guide us through getting an agent installed and configured to check into Chocolatey Central Management and to be set up for handling deployment tasks. - -## Setup - -### Step 1: Install Chocolatey Agent - -First you need Chocolatey Agent installed. As there may be some steps involved with the install of the agent, please see [Chocolatey Agent Setup](xref:setup-agent). - -### Step 2: Update Configuration - -At a minimum you need the following items set to be able to have a Chocolatey Agent be "opted-in" for both checking into Chocolatey Central Management and Deployments: - -```powershell -choco config set --name CentralManagementServiceUrl --value https://:24020/ChocolateyManagementService -choco feature enable --name="'useChocolateyCentralManagement'" -# Requires Chocolatey Licensed Extension v2.1.0+, Chocolatey-Agent v0.10.0+, and Chocolatey Central Management v0.2.0+: -choco feature enable --name="'useChocolateyCentralManagementDeployments'" -``` - -> :choco-warning: **WARNING** -> -> The Chocolatey Agent installed on the same machine that has the CCM Service installed will share the `centralManagementServiceUrl` setting, so that agent can only report into that CCM Service. - - -Please see config settings and features below for a full list. - -> :choco-info: **NOTE** -> -> As these features have security considerations as it is enabling cross-machine communication, they must be turned on explicitly. -> If you decide you want to open this up for over the internet communication, you should also set `centralManagementClientCommunicationSaltAdditivePassword` and `centralManagementServiceCommunicationSaltAdditivePassword` - see [Configuration](#config-settings) below. - -#### Config Settings - -* `centralManagementServiceUrl` = **' '** - The URL that should be used to communicate with Chocolatey Central Management. It should look something like https://servicemachineFQDN:24020/ChocolateyManagementService. See [FQDN usage](xref:ccm#fqdn-usage). Defaults to '' (empty). Available in business editions only. -* `centralManagementReportPackagesTimerIntervalInSeconds` = **'1800'** - Amount of time, in seconds, between each execution of the background service to report installed and outdated packages to Chocolatey Central Management. Defaults to '1800'. Available in business editions only. -* `centralManagementReceiveTimeoutInSeconds` = **'30'** - The amount of time, in seconds, that the background agent should wait to receive information from Chocolatey Central Management. Defaults to '30'. Available in business editions only. -* `centralManagementSendTimeoutInSeconds` = **'30'** - The amount of time, in seconds, that the background agent should wait to send information to Chocolatey Central Management. Defaults to '30'. Available in business editions only. -* `centralManagementCertificateValidationMode` = **'PeerOrChainTrust'** - The certificate mode that is used in communication to Chocolatey Central Management. Defaults to 'PeerOrChainTrust'. Available in business editions only. -* `centralManagementMaxReceiveMessageSizeInBytes` = **'2147483647'** - The size of the permitted message, in bytes, which can be exchanged between the Chocolatey Background Agent and Chocolatey Central Management. Defaults to '2147483647'. Available in business editions only. -* `centralManagementDeploymentCheckTimerIntervalInSeconds` = **'180'** - Amount of time, in seconds, between each execution of the Chocolatey Agent service to check for a new Deployment Step from Chocolatey Central Management. Defaults to '180'. Available in business editions only. -* `centralManagementClientCommunicationSaltAdditivePassword` = **' '** - Chocolatey Central Management Client Communication Salt Additive - The salt additive to use in the salt recipe for encrypting and verifying communication from an agent TO an instance of Central Management Service (will need to be set the same on all clients contacting that service AND the instance of the management service itself). When not set a default encryption phrase set by the system will be used. When set the unencrypted value must match exactly with what is set in the configuration for Central Management Service and every client contacting that instance of Central Management Service. Value is not shared over the wire. Because this is a much more involved process, it is recommended only setting this if you are transmitting messages over the internet. Defaults to ''. Needs to be at least 8 characters long if set or it will throw errors and use the default. Available in business editions only. IMPORTANT: If this value is set, agents less than v0.10.0 will be unable to contact Central Management to report in. -* `centralManagementServiceCommunicationSaltAdditivePassword` = **' '** - Chocolatey Central Management Communication Salt Additive - The salt additive to use in the salt recipe for encrypting and verifying communication FROM an instance of Central Management Service to an agent (will need to be set the same on all clients contacting that service AND the instance of the management service itself). When not set a default encryption phrase set by the system will be used. When set the unencrypted value must match exactly with what is set in the configuration for Central Management Service and every client contacting that instance of Central Management Service. Value is not shared over the wire. Because this is a much more involved process, it is recommended only setting this if you are transmitting messages over the internet. Defaults to ''. Needs to be at least 8 characters long if set or it will throw errors and use the default. Available in business editions only. - -> :choco-warning: **WARNING** -> -> The Chocolatey Agent installed on the same machine that has the CCM Service installed will share the `centralManagementServiceUrl` setting, so that agent can only report into that CCM Service. - -Also found at [Chocolatey Configuration](xref:configuration). - -#### Features - -* [ ] `useChocolateyCentralManagement` - Use Chocolatey Central Management - Lists of installed and outdated packages will be reported to the chosen Chocolatey Central Management server. Business editions only (version 2.0.0+). See [docs](xref:ccm) -* [ ] `useChocolateyCentralManagementDeployments` - Use Chocolatey Central Management Deployments - Centrally managed deployments of packages and scripts can be sent from Chocolatey Central Management. Business editions only (version 2.1.0+). See [docs](xref:ccm) - -Also found at [Chocolatey Configuration](xref:configuration). - -### Step 3: Verify Installation - -* Open the services snap-in (services.msc) and check for the presence of the `Chocolatey Agent` which should be in the started state. -* The installation folder for `chocolatey-agent` is at `$env:ChocolateyInstall\lib\chocolatey-agent\tools\service`. -* Open the Service log file located at `$env:ChocolateyInstall\logs\chocolatey-agent.log` and verify that there are no recently reported errors. If you are on a version of Chocolatey Agent prior to 0.10.0, the log will be located at `$env:ChocolateyInstall\lib\chocolatey-agent\tools\service\logs\chocolatey-agent.log`. -* There should be messages of connecting to the ccm server and checking in. It will be similar to this: - ![Agent Setup For CCM](/assets/images/features/ccm/agent_ccm_setup_good.png) - Connection to report in: - ![Agent Check-in to CCM](/assets/images/features/ccm/agent_ccm_communication.png) - -## FAQ - -### Can I run Self-Service and Chocolatey Central Management Deployments at the same time? -Yes - -### How can I increase the level of logging for Chocolatey Central Management? - -This can be done by changing the level value, which should be currently `INFO`, to use `DEBUG`, as per the following: - -```xml - - - - - -``` - -In the following files: - -* `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\log4net.config`. If you are on a version less than 0.2.0, then it will be in `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\chocolatey-central-management.exe.config`. -* `$env:ChocolateyInstall\lib\chocolatey-agent\tools\service\chocolatey-agent.exe.config` - -When the value is changed, the services may also need restarted. - -### Can I save an image with the agent already installed that I can deploy new machines from? - -Yes, however you need to keep in mind that there is a unique machine Id that will need to be erased so it can be regenerated. - -Make sure to include the following in your provisioning script to deploy the new images: - -```powershell -Write-Host "Removing Chocolatey Unique Machine GUID" -Remove-ItemProperty -Path "HKLM:\Software\Chocolatey" -Name "UniqueId" -Force -# Restart the Agent Service if it is running -``` - -Once you've removed this, you'll need to restart the Agent Service to get it regenerated. - -> :choco-info: **NOTE** -> -> You may **also** need to remove the ChocolateyLocalAdmin user (if you are using it for services) and reinstall the Agent service (and CCM service if on this machine) to get that password corrected. - -### What is the CCM compatibility matrix? - -Central Management has specific compatibility requirements with quite a few moving parts. It is important to understand that there are some Chocolatey Agent versions that may not be able to communicate with some versions of CCM and vice versa. Please see the [CCM Component Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix) for details. - -### What is Run Actual? - -You may have seen `--run-actual`, what is that? - -This is a switch that is passed to opt out of Chocolatey Self-Service. It's typically passed by the agent service back to choco to run a command for a user. You typically would not issue this, but the agent service will, so you are likely to see it in the logs if you are looking closely. - -### Where is the agent service installed? - -The installation folder for `chocolatey-agent` is at `$env:ChocolateyInstall\lib\chocolatey-agent\tools\service`. - -## Common Errors And Resolutions - -### Unable to report computer information to CCM - -You may see messaging like the following in the chocolatey-agent.log: - -```sh -[INFO ] - Creating secure channel to https://ccmserver:24020/ChocolateyManagementService ahead of CCM check-in... -[ERROR] - Unable to report computer information to CCM.: - The message with Action 'http://tempuri.org/IChocolateyManagementService/report_computer_information' cannot be - processed at the receiver, due to a ContractFilter mismatch at the EndpointDispatcher. This may be because of either a - contract mismatch (mismatched Actions between sender and receiver) or a binding/security mismatch between the sender - and the receiver. Check that sender and receiver have the same contract and the same binding (including security - requirements, e.g. Message, Transport, None). -``` - -This is due to having a Chocolatey Agent that is v0.10.0+ versus an older Central Management Service (< v0.2.0). Newer agents are incompatible because they use newer and more secure methods of communication. Please upgrade Central Management to v0.2.0+ at your earliest convenience. Or if you are on CCM v0.3.0+, your agents need to be on v0.11.0+. Please refer to the [CCM Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix). - -### Unable to check for deployments from Chocolatey Central Management - -This will provide similar messaging as the above. The fix is the same, upgrade Chocolatey Central Management to v0.2.0+. Or if you are on CCM v0.3.0+, your agents need to be on v0.11.0+. Please refer to the [CCM Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix). You may need to be on at least v0.3.0 and agents on v0.11.0+ if you are experiencing improper passphrase issues noted below, it means you need to likely upgrade to v0.3.0+ / v0.11.0 across your infrastructure. - -### We are seeing the error "attempted to call report_computer_information with an improper passphrase" in the CCM Service log - -If you are in the CCM service logs, you may be seeing the above error. That is a bug that was found with the communication of CCM v0.2.0 and Chocolatey Agent v0.10.0. That was resolved in CCM v0.3.0 and Chocolatey Agent v0.11.0. Please see the [CCM Component Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix) and [Licensed Issue #152](https://github.com/chocolatey/chocolatey-licensed-issues/issues/152) for more details. - -### The client reports successful check-in, but nothing is showing up in CCM - -You need to check the CCM service logs. The agent will always report success when it communicates with the service successfully. The service may reject what it receives, but due to security settings, it won't tell the client about that. - -The logs are located at `$env:ChocolateyInstall\logs\ccm-service.log`. If you are on a version of CCM prior to 0.2.0, the log will be located at `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\logs\chocolatey.service.host.log`. - -### Chocolatey Agent Service is unable to communicate with Chocolatey Central Management Service - -There is a known issue with the beta release of Chocolatey Central Management where an inconsistent Port Number is used between these two services. One used 24020 and the other used 24040. The correct default Port Number is 24020, and this is used in the 0.1.0 release of Chocolatey Central Management. If required, the Port Number can be explicitly set during the installation of the Chocolatey Central Management packages using the following option when installing `chocolatey-management-service`: - -```powershell ---params="'/PortNumber=24020'" -``` - -### The remote server returned an unexpected response: (413) Request Entity Too Large - -When reporting a larger number of packages (approximately 200), this error may be reported. This is due to the size of the information, in bytes, being too large to send between the Chocolatey Agent Service and the Chocolatey Central Management Service. This has been identified as a [bug](https://github.com/chocolatey/chocolatey-licensed-issues/issues/95), which is due to be corrected in version 0.1.1 of Chocolatey Central Management - -### Computers checking in are overwriting each other - -You are generating machines from a base image that already had Chocolatey commercial code on it. This is okay, but you need to remove the Chocolatey Machine Id Guid, which is used to identify a machine as unique. - -When the licensed agent service is installed on a machine, a unique machine id is given to the machine. If you are starting from a template, there is no opportunity for that to be different and when those machines start checking in, they will start overwriting each other. - -Basically you need to go find the machine id at `HKEY_LOCAL_MACHINE\SOFTWARE\Chocolatey\` (`UniqueId`) and remove it as part of your image deployment mechanism. - -```powershell -Write-Host "Removing Chocolatey Unique Machine GUID" -Remove-ItemProperty -Path "HKLM:\Software\Chocolatey" -Name "UniqueId" -Force -# Restart the Agent Service if it is running -``` - -Once you've removed this, you'll need to restart the Agent Service to get it regenerated. - -> :choco-info: **NOTE** -> -> You may **also** need to remove the ChocolateyLocalAdmin user (if you are using it for services) and reinstall the Agent service (and CCM service if on this machine) to get that password corrected. - -### The agent services are not picking up the new license - -Currently, you do need to restart agents. Here's a handy script: - -```powershell -Get-Service chocolatey-* | Stop-Service -Get-Service chocolatey-* | Start-Service -``` - -[Central Management Setup](xref:ccm-setup) | [Chocolatey Central Management](xref:central-management) diff --git a/input/en-us/central-management/setup/database.md b/input/en-us/central-management/setup/database.md deleted file mode 100644 index 7d55ff2f3c..0000000000 --- a/input/en-us/central-management/setup/database.md +++ /dev/null @@ -1,492 +0,0 @@ ---- -Order: 10 -xref: ccm-database -Title: Database -Description: Information on how to setup the CCM Database -RedirectFrom: docs/central-management-setup-database ---- - -At the end of this, we should have a fully ready to go SQL Server: - -* Installed -* Configured -* Database package deployed creating the database -* Permissions added - -> :choco-warning: **WARNING** -> -> Unless otherwise noted, please follow these steps in **exact** order. These steps build on each other and need to be completed in order. - -## Step 1: Complete Prerequisites - -* [High-level Requirements](xref:ccm-setup#high-level-requirements) -* SQL Server 2012 or later. - -> :choco-info: **NOTE** -> -> While we'd like to support different database engines at some point in the distant future, currently only SQL Server is supported. - -Chocolatey Central Management will not install or take a dependency on a database engine install as there are different editions that could be installed and multiple packages out there. At this time, it is expected that you have this ready. This is required before you can continue to other steps. - -* You need a SQL Server set up somewhere. Editions really don't matter until you have a large number of computers checking in. -* SQL Server should support mixed mode for logins (unless you are going to use AD authentication). 98% of the time you are going to want mixed mode authentication for SQL Server unless you hit options. -* You need to create the user access to the database (logins at the server level/users at the db level). - -> :choco-warning: **WARNING** -> -> SQL Server Mixed Mode Authentication is what you will want for ease of installation. If you decide you need to go Windows Authentication (aka integrated security), you **will** need to ensure the following additional items: -> -> * **You *must* have active directory** - Full stop. Local machine accounts can not authenticate to remote machines (nor SQL Server instances on remote machines). -> * **SQL Server machine security** - ensure the domain accounts being used for the service and web are not local administrators (members of the `BUILTIN\Administrators`) group on the machine that contains the SQL Server instance, or they will have `sysadmin` privileges by default to the SQL Server instance (until removed). -> * **Chocolatey Central Management Service installation** - You'll need to use an Active Directory (LDAP) account. See the install options for how to pass that through. -> * **!!Security!!** - As part of installation, an account will be made a member of the `BUILTIN\Administrators` group on the machine where the service is installed. Ensure that is **not** the same machine where SQL Server is installed or that account will immediately be a member of the `sysadmin` role by default in SQL Server (until removed). -> * **Chocolatey Central Management Web installation** - You'll need to use an Active Directory (LDAP) account. See the install options for how to pass that through to be set with the IIS Application Pool. -> -> :choco-info: **NOTE** -> -> Incorrect credentials to the database is 90% of support tickets related to Chocolatey Central Management. -> -> Unless you are an expert in hooking things up to SQL Server, its probably best to stick with SQL Server Mixed Mode Authentication. -> See - -### Step 1.1: Install SQL Server - -You may need to install SQL Server as part of this. There are all kinds of ways to do that and different SKUs to choose from. If you already have SQL Server implemented and you simply want to add the Chocolatey Management Database to that, you can skip this step (and possibly 1.2 as well). - -#### Install SQL Server Express - -You may have other methods for getting SQL Server installed, but if you are looking for a quick way of installing SQL Server Express, you can use the Chocolatey packages we internalized earlier in this process. - -The quickest option to get going with the database is to use the Chocolatey Community Repository, or an internalized version of a SQL Server package from the community repository. For SQL Server Express 2022, run the following: - -```powershell -choco install sql-server-express -y -``` - -You will also want to have the management tools installed, which can be installed with: - -```powershell -choco install sql-server-management-studio -y -``` - -### Step 1.2: Prepare SQL Server - -In preparing SQL Server, you need to do the following: - -* Turn on Named Pipes and TCP Server protocols -* Ensure the TcpPort is 1433 (or know what it is you need to connect to) -* Set SQL Server Mixed Mode Authentication -* Restart SQL Server -* Open Windows Firewall ports for TCP access (and SQL Server Browser in most cases) - -We've prepared a handy script (that may turn into a package later) to help you ensure you have SQL Server set up properly. - -#### Script to Prepare SQL Server Express - -The following is a script for SQL Server Express. You may be configuring a default instance. This should be run on the computer that has SQL Server Express installed as it will have the right binaries necessary for accessing SQL Server programmatically. - -> :choco-warning: **WARNING** -> -> This script is SQL Server version dependent! Please see the TODO in the script below and adjust accordingly. - -```powershell -# https://docs.microsoft.com/en-us/sql/tools/configuration-manager/tcp-ip-properties-ip-addresses-tab -Write-Output "SQL Server: Configuring Remote Access on SQL Server Express." -$assemblyList = 'Microsoft.SqlServer.Management.Common', 'Microsoft.SqlServer.Smo', 'Microsoft.SqlServer.SqlWmiManagement', 'Microsoft.SqlServer.SmoExtended' - -foreach ($assembly in $assemblyList) { - $assembly = [System.Reflection.Assembly]::LoadWithPartialName($assembly) -} - -$wmi = New-Object Microsoft.SqlServer.Management.Smo.Wmi.ManagedComputer # connects to localhost by default -$instance = $wmi.ServerInstances | Where-Object { $_.Name -eq 'SQLEXPRESS' } - -$np = $instance.ServerProtocols | Where-Object { $_.Name -eq 'Np' } -$np.IsEnabled = $true -$np.Alter() - -$tcp = $instance.ServerProtocols | Where-Object { $_.Name -eq 'Tcp' } -$tcp.IsEnabled = $true -$tcp.Alter() - -$tcpIpAll = $tcp.IpAddresses | Where-Object { $_.Name -eq 'IpAll' } - -$tcpDynamicPorts = $tcpIpAll.IpAddressProperties | Where-Object { $_.Name -eq 'TcpDynamicPorts' } -$tcpDynamicPorts.Value = "" -$tcp.Alter() - -$tcpPort = $tcpIpAll.IpAddressProperties | Where-Object { $_.Name -eq 'TcpPort' } -$tcpPort.Value = "1433" -$tcp.Alter() - -# TODO: THIS LINE IS VERSION DEPENDENT! Replace MSSQL16 with whatever version you have -Write-Output "SQL Server: Setting Mixed Mode Authentication." -New-ItemProperty 'HKLM:\Software\Microsoft\Microsoft SQL Server\MSSQL16.SQLEXPRESS\MSSQLServer\' -Name 'LoginMode' -Value 2 -Force -# VERSION DEPENDENT ABOVE - -Write-Output "SQL Server: Forcing Restart of Instance." -Restart-Service -Force 'MSSQL$SQLEXPRESS' - -Write-Output "SQL Server: Setting up SQL Server Browser and starting the service." -Set-Service 'SQLBrowser' -StartupType Automatic -Start-Service 'SQLBrowser' - -Write-Output "Firewall: Enabling SQLServer TCP port 1433." -netsh advfirewall firewall add rule name="SQL Server 1433" dir=in action=allow protocol=TCP localport=1433 profile=any enable=yes service=any -#New-NetFirewallRule -DisplayName "Allow inbound TCP Port 1433" –Direction inbound –LocalPort 1433 -Protocol TCP -Action Allow - -Write-Output "Firewall: Enabling SQL Server browser UDP port 1434." -netsh advfirewall firewall add rule name="SQL Server Browser 1434" dir=in action=allow protocol=UDP localport=1434 profile=any enable=yes service=any -#New-NetFirewallRule -DisplayName "Allow inbound UDP Port 1434" –Direction inbound –LocalPort 1434 -Protocol UDP -Action Allow -``` - -## Step 2: Install Chocolatey Central Management Database Package - -The Chocolatey Central Management Database package: - -* Creates the `ChocolateyManagement` database if it does not exist. -* Migrates the database code (`DDL/DML`) to bring it up to the current version. -* That's it. - -> :choco-warning: **WARNING** -> -> Chocolatey Central Management packages do **NOT** install SQL Server. You must take care of that in the prerequisites. Do not even start on Chocolatey Central Management installs until you have a SQL Server instance up and ready. I repeat, SQL Server engine must be already installed. - -The Chocolatey Central Management database package will add or update a database to an existing SQL Server instance. - -> :choco-info: **NOTE** -> -> When you run this package installation, you will want to do so as integrated security, or with Windows Authentication. When you run the other two package installations, you will want to do so providing a connection string. - -### Package Parameters - -* `/ConnectionString:` - The SQL Server database connection string to be used to connect to the Chocolatey Central Management database. Defaults to default or explicit values for `/SqlServiceInstance` and `/Database`, along with Integrated Security (`Server=; Database=ChocolateyManagement; Trusted_Connection=True;`). The account should have `db_owner` access to the database ([database owner](https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/database-level-roles#fixed-database-roles)). -* `/SqlServerInstance:` - Instance name of the SQL Server database to connect to. Alternative to passing full connection string with `/ConnectionString`. Uses `/Database` (below) to build a connection string. Defaults to ``. -* `/Database:` - Name of the SQL Server database to use. Alternative to passing full connection string with `/ConnectionString`. Uses `/SqlServerInstance` (above) to build a connection string. Defaults to `ChocolateyManagement`. -* `/SkipDatabasePermissionCheck` - By default, a check will be completed to ensure that the installing user has access to create a new database, based on the provided/computed connection string. If this check isn't required, for example, the database has already been created or permissions will error, this step can be skipped using this parameter. Available with CCM v0.2.0+. - -> :choco-info: **NOTE** -> -> Items suffixed with "`:`" mean a value should be provided. Items without are simply switches. - -### Database Authentication Scenarios - -* [Scenario 1 - Windows Authentication to Local SQL Server](xref:ccm-database#scenario-one) -* [Scenario 2 - Active Directory Authentication to Remote SQL Server](xref:ccm-database#scenario-two) -* [Scenario 3 - SQL Server Authentication to Local SQL Server](xref:ccm-database#scenario-three) -* [Scenario 4 - SQL Server Authentication to Remote SQL Server](xref:ccm-database#scenario-four) - - - -::::{.tab-content .text-bg-body-secondary .p-3 .mb-3 .border-start .border-end .border-bottom .rounded-bottom} -:::{.tab-pane .fade .show .active #scenario-one role=tabpanel aria-labelledby=scenario-one-tab} - -#### Windows Authentication to Local SQL Server - -You have set up the database to use Windows Authentication (or Mixed Mode Authentication). You are installing the database package on a single server, but connecting to an existing SQL Server in your environment. - -##### Licensed SQL Server - -```powershell -choco install chocolatey-management-database -y --package-parameters='/ConnectionString=""Server=Localhost;Database=ChocolateyManagement;Trusted_Connection=true;""' -``` - -> :choco-info: **NOTE** -> -> Note the connection string doesn't include credentials. That's because Windows Authentication for SQL Server uses the context of what is running the process, whether that be a domain account or a local Windows account. -> -> You can use `--package-parameters` and/or `--package-parameters-sensitive` here, depending on whether you are specifying things that should not be logged (`--package-parameters-sensitive` is guaranteed to stay out of logs). - -> :choco-warning: **WARNING** -> -> **Installs**: Please ensure the user running the package installation is able to create databases unless you also pass `/SkipDatabasePermissionCheck` (in that case you simply need `db_owner` to the database being managed if it was pre-created). -> -> **Upgrades**: Please ensure the user running the package installation has been granted `db_owner` access to an existing database. - ---- - -##### SQL Server Express - -```powershell -choco install chocolatey-management-database -y --package-parameters='/ConnectionString=""Server=Localhost\SQLEXPRESS;Database=ChocolateyManagement;Trusted_Connection=true;""' -``` - -> :choco-info: **NOTE** -> -> The above warnings and notes apply here as well. - -::: -:::{.tab-pane .fade #scenario-two role=tabpanel aria-labelledby=scenario-two-tab} - -#### Active Directory Authentication to Remote SQL Server - -You have set up the database to use Windows Authentication (or Mixed Mode Authentication). You are installing the database package on a different server than your existing SQL Server is located on. - -```powershell -choco install chocolatey-management-database -y --package-parameters='/ConnectionString=""Server=;Database=ChocolateyManagement;Trusted_Connection=true;""' -``` - -> :choco-danger: **DANGER** -> -> SLOW DOWN right here. -> -> We recommend keeping the package installations on the same machine as SQL Server. It will reduce confusion and increase the accuracy of reporting. Run the installs/upgrades on the machine they apply to, so this should be the same machine that contains SQL Server (if on Windows). -> - -> :choco-warning: **WARNING** -> -> **Installs**: Please ensure the user running the package installation is able to create databases unless you also pass `/SkipDatabasePermissionCheck` (in that case you simply need `db_owner` to the database being managed if it was pre-created). -> -> **Upgrades**: Please ensure the user running the package installation has been granted `db_owner` access to an existing database. - -::: -:::{.tab-pane .fade #scenario-three role=tabpanel aria-labelledby=scenario-three-tab} - -#### SQL Server Authentication to Local SQL Server - -The database has been setup to use Mixed Mode Authentication. Someone has already pre-created the login credentials for a SQL Server account and ensured the user has `db_owner` permissions to allow for changing schema. There is a high likelihood that the database has been pre-created. Now you want to install the package on the same machine where the sql server instance is located. - -##### Licensed SQL Server - -```powershell -choco install chocolatey-management-database -y --package-parameters="'/SkipDatabasePermissionCheck'" --package-parameters-sensitive='/ConnectionString=""Server=Localhost;Database=ChocolateyManagement;User ID=ChocoUser;Password=Ch0c0R0cks;""' -``` - -> :choco-warning: **WARNING** -> -> **Installs**: Please ensure the login credentials provided are able to create databases unless you also pass `/SkipDatabasePermissionCheck` (in that case you simply need `db_owner` to the database being managed if it was pre-created). -> -> **Upgrades**: Please ensure the login credentials provided have been given `db_owner` access to an existing database. - ---- - -##### SQL Server Express - -```powershell -choco install chocolatey-management-database -y --package-parameters-sensitive='/ConnectionString=""Server=Localhost\SQLEXPRESS;Database=ChocolateyManagement;User ID=ChocoUser;Password=Ch0c0R0cks;""' -``` - -> :choco-info: **NOTE** -> -> The above warnings and notes apply here as well. - -::: -:::{.tab-pane .fade #scenario-four role=tabpanel aria-labelledby=scenario-four-tab} - -#### SQL Server Authentication to Remote SQL Server - -The database has been setup to use Mixed Mode Authentication. Someone has already pre-created the login credentials for a SQL Server account and ensured the user has `db_owner` permissions to allow for changing schema. There is a high likelihood that the database has been pre-created. Now you want to install the package on a different machine than where the sql server instance is located. - -```powershell -choco install chocolatey-management-database -y --package-parameters="'/SkipDatabasePermissionCheck'" --package-parameters-sensitive='/ConnectionString=""Server=;Database=ChocolateyManagement;User ID=ChocoUser;Password=Ch0c0R0cks;""' -``` - -> :choco-danger: **DANGER** -> -> SLOW DOWN right here. -> -> We recommend keeping the package installations on the same machine that SQL Server is in. It will reduce confusion and increase the accuracy of reporting. Run the installs/upgrades on the machine they apply to, so this should be the same machine that contains SQL Server (if on Windows). - -> :choco-warning: **WARNING** -> -> **Installs**: Please ensure the login credentials provided are able to create databases unless you also pass `/SkipDatabasePermissionCheck` (in that case you simply need `db_owner` to the database being managed if it was pre-created). -> -> **Upgrades**: Please ensure the login credentials provided have been given `db_owner` access to an existing database. - -::: -:::: - -## Step 3: Set up SQL Server Logins And Access - -Once we have the database, we can create logins and map those logins to users in the database. - -> :choco-warning: **WARNING** -> -> Chocolatey Central Management packages do **NOT** configure SQL Server access. - -The difference between a login and a user when it comes to SQL Server accounts has long confused folks. Simply put: - -* Login (Authentication) - A login is at instance level (the credentials or Windows-based accounts) - [https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/create-a-login](https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/create-a-login) -* User (Authorization) - A user is that login being mapped to a database and given roles/privileges (an instance can contain multiple databases) - [https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/create-a-database-user](https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/create-a-database-user) - -Notes: - -* Grant `db_datareader` and `db_datawriter` to the accounts you create for the web and service. -* You can share the same login for the two accounts, unless your internal best practices dictate using different passwords. - -```powershell -function Add-DatabaseUserAndRoles { - [CmdletBinding()] - param( - [Parameter(Mandatory=$true)] - [string] $Username, - - [Parameter(Mandatory=$true)] - [string] $DatabaseName, - - [Parameter(Mandatory=$false)] - [string] $DatabaseServer = 'localhost\SQLEXPRESS', - - [Parameter(Mandatory=$false)] - [string[]] $DatabaseRoles = @('db_datareader'), - - [Parameter(Mandatory=$false)] - [string] $DatabaseServerPermissionsOptions = 'Trusted_Connection=true;', - - [Parameter(Mandatory=$false)] - [switch] $CreateSqlUser, - - [Parameter(Mandatory=$false)] - [string] $SqlUserPassword - ) - - $LoginOptions = "FROM WINDOWS WITH DEFAULT_DATABASE=[$DatabaseName]" - if ($CreateSqlUser) { - $LoginOptions = "WITH PASSWORD='$SqlUserPassword', DEFAULT_DATABASE=[$DatabaseName], CHECK_EXPIRATION=OFF, CHECK_POLICY=OFF" - } - - $addUserSQLCommand = @" -USE [master] -IF EXISTS(SELECT * FROM msdb.sys.syslogins WHERE UPPER([name]) = UPPER('$Username')) -BEGIN - DROP LOGIN [$Username] -END - -CREATE LOGIN [$Username] $LoginOptions - -USE [$DatabaseName] -IF EXISTS(SELECT * FROM sys.sysusers WHERE UPPER([name]) = UPPER('$Username')) -BEGIN - DROP USER [$Username] -END - -CREATE USER [$Username] FOR LOGIN [$Username] - -"@ - - foreach ($DatabaseRole in $DatabaseRoles) { - $addUserSQLCommand += @" - -ALTER ROLE [$DatabaseRole] ADD MEMBER [$Username] -"@ - } - - Write-Output "Adding $UserName to $DatabaseName with the following permissions: $($DatabaseRoles -Join ', ')" - Write-Debug "running the following: \n $addUserSQLCommand" - - - $Connection = New-Object System.Data.SQLClient.SQLConnection - $Connection.ConnectionString = "server='$DatabaseServer';database='master';$DatabaseServerPermissionsOptions" - $Connection.Open() - $Command = New-Object System.Data.SQLClient.SQLCommand - $Command.CommandText = $addUserSQLCommand - $Command.Connection = $Connection - $Command.ExecuteNonQuery() - $Connection.Close() -} - -# Please choose from one of the three listed account types below. The commands will grant database permissions to a user account of your choice. This account will be used in your Connection String for the CCM Service and Web package installs ahead. - -# Add Sql Server Login / User: -Add-DatabaseUserAndRoles -DatabaseName 'ChocolateyManagement' -Username 'ChocoUser' -SqlUserPassword '' -CreateSqlUser -DatabaseRoles @('db_datareader', 'db_datawriter') - -# Add Local Windows User: -Add-DatabaseUserAndRoles -DatabaseName 'ChocolateyManagement' -Username "$(hostname)\ChocolateyLocalAdmin" -DatabaseRoles @('db_datareader', 'db_datawriter') - -# Add Active Directory Domain User to a default instance of SQL Server: -Add-DatabaseUserAndRoles -DatabaseServer 'localhost' -DatabaseName 'ChocolateyManagement' -Username "\" -DatabaseRoles @('db_datareader', 'db_datawriter') -``` - -## Step 4: Verify Installation - -The purpose of the `chocolatey-management-database` package is to create and deploy the schema for the database that is used by the Chocolatey Central Management Service and Website. This can be verified by using something like SQL Server Management Studio to connect to the SQL Server Instance and: - -* Check that a database (by default named `ChocolateyManagement`) has been created -* That a set of tables have been created within this database -* That permissions have been set for accounts - -## FAQ - -### Can I use MySQL (or PostgreSQL)? - -Unfortunately only SQL Server SKUs work with Chocolatey Central Management at this time. You can use SQL Server Express in smaller shops without additional costs. - -### What is the Chocolatey Central Management compatibility matrix? - -Chocolatey Central Management has specific compatibility requirements with quite a few moving parts. It is important to understand that there are some Chocolatey Agent versions that may not be able to communicate with some versions of Chocolatey Central Management and vice versa. Please see the [Chocolatey Central Management Component Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix) for details. - -### What is the minimum required configuration for the appsettings.json file? - -As of Chocolatey Central Management v0.6.2, the default settings in the `appsettings.json` for the database package are: - -```json -{ - "ConnectionStrings": { - "Default": "Server=; Database=ChocolateyManagement; Trusted_Connection=True;" - } -} -``` - -> :choco-info: **NOTE** -> -> This file will usually be condensed into a single line with the values encrypted. - -## Common Errors and Resolutions - -### Chocolatey Central Management database package installs without error, but ChocolateyManagement database is not created - -In the beta version of the Chocolatey Central Management database package, if there was an error during the creation of the database, no exit code was used. As a result, the package could state that it was installed correctly, but the database would not have been created. This has been corrected in the 0.1.0 release of Chocolatey Central Management. - -When this occurs, the problem is typically the connection string being used to connect to the database. The advice is to verify that the connecting string is valid, and attempt the installation again. - -### The term 'Install-ChocolateyAppSettingsJsonFile' is not recognized as the name of a cmdlet, function, script file, or operable program. - -In the beta version of Chocolatey.Extension, there was a Cmdlet named Install-ChocolateyAppSettingsJsonFile and this was used in the 0.1.0-beta-20181009 release of the Chocolatey Central Management components. In the final released version of the Chocolatey.Extension, this was renamed to Install-AppSettingsJsonFile. - -As a result, the Chocolatey Central Management beta no longer works with the released version of Chocolatey.Extension. This will be corrected once the next release of the Chocolatey Central Management components is completed. - -### Cannot process command because of one or more missing mandatory parameters: FilePath - -During the creation of Chocolatey Central Management, some additional PowerShell cmdlets were created, and these are installed as part of the Chocolatey Extension package. These cmdlets went through a number of iterations, and as a result, different combinations of Chocolatey Central Management packages were incompatible with the Chocolatey Extension package, resulting in the error: - -`Cannot process command because of one or more missing mandatory parameters: FilePath` - -The guidance in this case is either to pin to the specific version of the Chocolatey Extension package required by the version of Chocolatey Central Management being used, or update to the latest versions of all packages, where the situation should be addressed. - -### ERROR: The term ‘Install-SettingsJsonFile’ is not recognized as the name of a cmdlet, function, script file, or operable program. - -This is . - -There are two workarounds noted: - -* Delete the `appsettings.json` file prior to upgrade. -* Do not pass database details if they have not changed during upgrade. - -### ERROR: System.Data.SqlClient.SqlException: Could not allocate space for object 'dbo.AbpAuditLogs'.'PK_AbpAuditLogs' in database 'ChocolateyManagement' because the 'PRIMARY' filegroup is full. Create disk space by deleting unneeded files, dropping objects in the filegroup, adding additional files to the filegroup, or setting autogrowth on for existing files in the filegroup. - -This occurs when the `ChocolateyManagement` database has reached its maximum configured size. The following SQL query resolves the issue by increasing the database size to 200 MB. You can increase this value up to 10 GB (in MB notation) if using SQL EXPRESS or higher if using a licensed edition of SQL Server. Ensure you have the free space available to support whatever maximum you decide upon. - -```sql -USE master; -GO -ALTER DATABASE ChocolateyManagement -MODIFY FILE - (NAME = ChocolateyManagement, - SIZE = 200MB); -GO -``` - -[Central Management Setup](xref:ccm-setup) [Chocolatey Central Management](xref:central-management) diff --git a/input/en-us/central-management/setup/index.md b/input/en-us/central-management/setup/index.md deleted file mode 100644 index 638eb1f679..0000000000 --- a/input/en-us/central-management/setup/index.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -Order: 20 -xref: ccm-setup -Title: Setup -Description: Information on how to setup CCM -RedirectFrom: docs/central-management-setup ---- - -Installing CCM takes a little more pre-thought than simply running the package installs. -While it is envisioned that CCM will be installed across multiple servers (split installation), it is certainly possible to run CCM on a single server (monolithic). - -When setting up Central Management, currently, the CCM packages do not provision the SQL Server Database Permissions that are required for the CCM components to function. It is assumed that the necessary permissions have already been provided (see the [FAQ](#how-can-i-add-sql-server-permissions-through-powershell) for one method of doing it). - -> :choco-warning: **WARNING** -> -> * Unless otherwise noted, please follow these steps in **exact** order. These steps build on each other and need to be completed in order. -> -> * All deployed components of the CCM packages should **always** be the **SAME VERSION**. The only time you should not have this is when you are in a state of upgrading and that transition time should be quite short. -> - -> :choco-info: **NOTE** -> -> * Please read through all of this prior to running installation as you could run into issues that require support to help you correct later. -> -> * If this seems like a lot to set up, you have access to the [Quick Start Guide](xref:c4b-quick-start-guide) which makes setup of Chocolatey Central Management just running one Powershell script. We also offer our [Chocolatey For Business Azure Environment](xref:c4b-azure). It comes preloaded with Chocolatey Central Management and other Chocolatey recommended infrastructure. -> - -## High Level Requirements - -Central Management packages require at a minimum: - -* Chocolatey for Business (C4B) Edition -* Windows Server 2016 - -Each package further defines dependencies that they include. - -Additionally, the Chocolatey Central Management components should be installed onto servers having a static IP address assigned, in addition to an appropriately configured DNS A record. Failure to ensure this configuration is applied could lead to unexpected errors with agent check-in and deployment operations. - -## Step 1: Internalize Packages - -> :choco-info: **NOTE** -> -> Make sure you have read over the [CCM Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix) prior to starting internalization as this will save you some headaches. - -The complete installation of CCM requires several packages that are available from the community repository. Let's get them internalized. We will internalize them to a `C:\packages` directory. It is highly recommended that you push the packages to an internal repository before continuing with other steps in this guide. Change the values in the first lines of this script to match what you need in your environment. - -```powershell -# To run this, you need Chocolatey for Business installed (chocolatey / chocolatey.extension). - -# Update the values and remove the < > -$YourInternalRepositoryPushUrl = '' -$YourInternalRepositoryApiKey = '' -# You get this from the chocolatey.license.xml file: -$YourBusinessLicenseGuid = '' - -if(!(Test-Path C:\packages)){ - $null = New-Item C:\packages -ItemType Directory -} - -# Download Chocolatey community related items, no internalization necessary -choco download chocolatey chocolateygui --force --source="'https://community.chocolatey.org/api/v2/'" --output-directory="'C:\packages'" - -# This is for other Community Related Items -choco download dotnet4.5.2 dotnetfx --force --internalize --internalize-all-urls --append-use-original-location --source="'https://community.chocolatey.org/api/v2/'" --output-directory="'C:\packages'" - - -# This is for SQL Server Express -# Not necessary if you already have SQL Server -@('sql-server-express','sql-server-management-studio') | Foreach-Object { - choco download $_ --force --internalize --internalize-all-urls --append-use-original-location --source="'https://community.chocolatey.org/api/v2/'" --output-directory="'C:\packages'" -} - -# We must use the 6.x.x versions of these packages, so we need to download/internalize these specific items. At the time of publishing, the most recent version of this package is 6.0.5, but later package versions (within the 6.x.x release) are expected to work. -@('dotnet-6.0-runtime', 'dotnet-6.0-aspnetruntime') | Foreach-Object { - choco download $_ --version 6.0.5 --force --internalize --internalize-all-urls --append-use-original-location --source="'https://community.chocolatey.org/api/v2/'" --output-directory="'C:\packages'" -} - -# Starting with v0.9.0 of the CCM Website package, it uses dotnet-aspnetcoremodule-v2. At the time of publishing, the most recent version of this package 16.0.22108, but later package versions (within the 17.x.x release) are expected to work -choco download dotnet-aspnetcoremodule-v2 --version 16.0.22108 --force --internalize --internalize-all-urls --append-use-original-location --source="'https://community.chocolatey.org/api/v2/'" --output-directory="'C:\packages'" - -# Download Licensed Packages -## DO NOT RUN WITH `--internalize` and `--internalize-all-urls` - see https://github.com/chocolatey/chocolatey-licensed-issues/issues/155 -choco download chocolatey-agent chocolatey.extension chocolatey-management-database chocolatey-management-service chocolatey-management-web --force --source="'https://licensedpackages.chocolatey.org/api/v2/'" --ignore-dependencies --output-directory="'C:\packages'" --user="'user'" --password="'$YourBusinessLicenseGuid'" - -# Push all downloaded packages to your internal repository -Get-ChildItem C:\packages -Recurse -Filter *.nupkg | Foreach-Object { choco push $_.Fullname --source="'$YourInternalRepositoryPushUrl'" --api-key="'$YourInternalRepositoryApiKey'"} -``` - -## Step 2: Setup Central Management Database - -Please see [Central Management Database Setup](xref:ccm-database). - -> :choco-info: **NOTE** -> -> While we'd like to support different database engines at some point in the distant future, currently only SQL Server is supported. - -## Step 3: Setup Central Management Windows Service(s) - -Please see [Central Management Service Setup](xref:ccm-service). - -> :choco-info: **NOTE** -> -> If Step 1 is not succesful, do not move on to this step until you resolve issues with database setup. - -## Step 4: Setup Central Management Website - -Please see [Central Management Web Setup](xref:ccm-website). - -> :choco-info: **NOTE** -> -> If Step 1 or 2 is not successful, do not move on to this step until you resolve issues with previous steps. - -## Step 5: Setting up Agent Machines - -Please see [Central Management Client Setup](xref:ccm-client). - -## Upgrading? - -Looking for upgrade instructions? See [Central Management Upgrade](xref:ccm-upgrade). - -## Common Errors and Resolutions - -### Executable script code found in signature block - -When attempting to install some components of Chocolatey, you may have seen this error. This was a bug due to how the script at [Step 1: Internalize Packages](#step-1-internalize-packages) was [internalizing packages](https://github.com/chocolatey/chocolatey-licensed-issues/issues/155). - -Please go back through Step 1 and re-internalize those packages. You may need to overwrite any you would have pushed up (many if it won't let you do a push). In Nexus, you can remove the existing items and then upload through there. In other repositories you may need to remove the existing package versions you deployed first. - -### The client reports successful check-in, but nothing is showing up in CCM - -You need to check the CCM service logs. The agent will always report success when it communicates with the service successfully. The service may reject what it receives, but due to security settings, it won't tell the client about that. - -The logs are located at `$env:ChocolateyInstall\logs\ccm-service.log`. If you are on a version of CCM prior to 0.2.0, the log will be located at `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\logs\chocolatey.service.host.log`. - -[Chocolatey Central Management](xref:central-management) diff --git a/input/en-us/central-management/setup/service.md b/input/en-us/central-management/setup/service.md deleted file mode 100644 index 3f8a7e0a9a..0000000000 --- a/input/en-us/central-management/setup/service.md +++ /dev/null @@ -1,622 +0,0 @@ ---- -Order: 20 -xref: ccm-service -Title: Service -Description: Information on how to setup the CCM Service -RedirectFrom: docs/central-management-setup-service ---- - -This is the service that the agents (`chocolatey-agent`) communicates with. You could install one or more of these depending on the size of your environment (not multiple on one machine though). The FQDN and certificate used determine what the URL will be for the agents to check into Chocolatey Central Management. - -> :choco-warning: **WARNING** -> -> Unless otherwise noted, please follow these steps in **exact** order. These steps build on each other and need to be completed in order. - -> :choco-warning: **WARNING** -> -> In order to run the Chocolatey Central Management Service a user with Administrator access is required. By default, a new user named `ChocolateyLocalAdmin` will be created and configured to run the Chocolatey Central Management Service. In addition, `Logon as Service` and `Logon as Batch` privileges will be asserted for this user. If attempting to run the Chocolatey Central Management Service as a different user, these permissions will be required. - -## Step 1: Complete Prerequisites - -> :choco-warning: **WARNING** -> -> The [database](xref:ccm-database) must be setup and available, along with [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - -* [High-level Requirements](xref:ccm-setup#high-level-requirements) -* PowerShell 5.1 - -## Step 2: Install Chocolatey Central Management Service Package - -By default the service will install as the local administrative user `ChocolateyLocalAdmin` (and manage the password as well). However you can specify your own user with package parameters (such as using a domain account). You will need to specify credentials to the database as we'll see in scenarios below. - -> :choco-warning: **WARNING** -> -> Timezones are super important here and time synchronization is really important when generating SSL Certificates. You want to make sure this information is correct. Otherwise there is a potential edge case you could generate an SSL Certificate that is not yet valid. As the service package could generate an SSL certificate if you don't pass an existing thumbprint, it's best to ensure that time synchronization is not an issue with the machine you are installing this on. - -### FQDN Usage - -When installing the Chocolatey Central Management Service, the default is to use the Fully Qualified Domain Name (FQDN) of the machine that it is being installed on. As a result, there is an expectation that the certificate (either the self-signed certificate that is created during installation, or the existing certificate which is configured with the [CertificateThumbprint](#package-parameters-1) parameter) that is used to secure the transport layer of this service also uses the same FQDN. - -```powershell -# Find FDQN for current machine -$hostName = [System.Net.Dns]::GetHostName() -$domainName = [System.Net.NetworkInformation.IPGlobalProperties]::GetIPGlobalProperties().DomainName - -if(-Not $hostName.endswith($domainName)) { - $hostName += "." + $domainName -} - -choco config set --name="'centralManagementServiceUrl'" --value="'https://$($hostname):24020/ChocolateyManagementService'" -``` - -If this is not the case, it will be necessary to provide the information to the package about the actual name for the machine that is being used. When using a self-signed certificate, this can be specified using the `CertificateDnsName`, and when using an existing certificate, no additional parameters are required. In both cases, it will be necessary to also set the `centralManagementServiceUrl` [configuration parameter](#centralmanagementserviceurl). This can be done using the following command: - -```powershell -choco config set --name="'centralManagementServiceUrl'" --value="'https://:24020/ChocolateyManagementService'" -``` - -### Package Parameters - -Note items with "`:`" mean a value should be provided. Items without are simply switches. - -* `/Username:` - Username to run the service under. Defaults to `ChocolateyLocalAdmin`. This should be a local Administrator - this is typically ensured during installation. `Logon as Service` and `Logon as Batch` privileges are also ensured. -* `/Password:` - Password for the user. Default is the [Chocolatey Managed Password](#chocolatey-managed-password). -* `/EnterPassword` - Receive the password at runtime as a secure string. Requires input at runtime whe installing/upgrading the package. -* `/NoRestartService` - Do not shut down and restart the service. You will need to restart later to take advantage of new service information. -* `/DoNotReinstallService` - Do not re-install the service. -* `/PortNumber:` - The port the Chocolatey Management Service will listen on. This will automatically create a rule to open the firewall on the port specified. Defaults to `24020`. -* `/CertificateDnsName:` - The DNS name of the self-signed certificate that is generated if no existing certificate thumbprint is provided using the `/CertificateThumbprint` parameter (below). Defaults to ``. -* `/CertificateThumbprint:` - Provide the thumbprint of an existing certificate (already installed in `LocalMachine\TrustedPeople` certificate store) to use for secure communication with clients. Defaults to a new self-signed SSL certificate on first installation / reuses existing on upgrades. -* `/ConnectionString:` - The SQL Server database connection string to be used to connect to the Chocolatey Central Management database. Defaults to default or explicit values for `/SqlServiceInstance` and `/Database`, along with Integrated Security (`Server=; Database=ChocolateyManagement; Trusted_Connection=True;`). The account should have `db_datareader`/`db_datawriter` access to the database ([data reader / data writer](https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/database-level-roles#fixed-database-roles)). -* `/SqlServerInstance:` - Instance name of the SQL Server database to connect to. Alternative to passing full connection string with `/ConnectionString`. Uses `/Database` (below) to build a connection string. Defaults to ``. -* `/Database:` - Name of the SQL Server database to use. Alternative to passing full connection string with `/ConnectionString`. Uses `/SqlServerInstance` (above) to build a connection string. Defaults to `ChocolateyManagement`. - -> :choco-info: **NOTE** -> -> Items suffixed with "`:`" mean a value should be provided. Items without are simply switches. - -### Service Settings - -* Service Name: **chocolatey-central-management** -* Service Displayname: **Chocolatey Central Management Service** -* Description: **Chocolatey Central Management Service is a service for Chocolatey** -* Service Startup: **Automatic** -* Service Username: **ChocolateyLocalAdmin** or '`/Username:`' - -### Chocolatey Central Management Service Configuration - -For most installations, the default values for the Chocolatey Central Management Service configuration should be all that is required. However, if you need to modify this configuration, then full details of what can be controlled is detailed on the [Chocolatey Central Management Service configuration page](xref:ccm-usage-service-configuration#chocolatey-configuration-file). - -### Chocolatey Configuration - -There are a number of different Chocolatey Configuration values that can be set for the Chocolatey Central Management Service. The main setting that _has_ to be set is detailed below, and you can find a complete list on the [Chocolatey Central Management Service configuration page](xref:ccm-usage-service-configuration#chocolatey-configuration-file). - -* `centralManagementServiceUrl` = **' '** (empty) - The URL that should be used to communicate with Chocolatey Central Management. It should look something like `https://servicemachineFQDN:24020/ChocolateyManagementService`. See [FQDN usage](xref:ccm#fqdn-usage). Defaults to '' (empty). NOTE: Chocolatey Agent and Chocolatey Central Management Service share this value on a machine that contains both. If blank, the Chocolatey Central Management Service will construct a URL based on defaults of the machine, but is required to be set for Agents. - -> :choco-warning: **WARNING** -> -> The Chocolatey Agent installed on the same machine that has the Chocolatey Central Management Service installed will share the `centralManagementServiceUrl` setting, so that agent can only report into that Chocolatey Central Management Service. - -### Chocolatey Managed Password - -When Chocolatey manages the password for a local Administrator, it creates a very complex password: - -* It is 32 characters long. -* It uses uppercase, lowercase, numbers, and symbols to meet very stringent complexity requirements. -* The password is different for every machine. -* Due to the way that it is generated, it is completely unguessable. -* No one at Chocolatey Software could even tell you what the password is for a particular machine without local access. - -### Chocolatey Central Management Service Windows Account Considerations - -* Windows Account (required, defaults to `ChocolateyLocalAdmin`) - * The Chocolatey Central Management Service requires **an** administrative account, whether that is a domain account or a local account - it just needs to be a local admin (a member of the Administrators group). - * The Chocolatey Central Management Service doesn't specifically require the `ChocolateyLocalAdmin` account. Any Windows account can be used. The `ChocolateyLocalAdmin` is used as the default if one is not specified. - * Upon use of an account during installation, it will make that account a member of the Administrators account. - * The account used will also be granted `LogonAsService` and `LogonAsBatch` privileges. -* Managed Password (optional, default) - * When the `ChocolateyLocalAdmin` account is used, it generates a managed password that is different on every machine. The password is 32 characters long, meets complexity requirements, and is basically very strong. - * To determine the managed password, it would take access to the box and someone from Chocolatey Software who has access to the algorithm used to generate the password (more information in the FAQs below). -* Rotating/Updating Passwords - * If a different account with a rotating password is used, the service will need to be updated with the new credentials and restarted soon after changing that password. - * The managed password is not currently updated/rotated, but it is something we are looking to implement once we have figured out the best approach to do so. - -### Database Authentication Scenarios - -* [Scenario 1 - Windows Authentication to Local SQL Server](xref:ccm-service#scenario-one) -* [Scenario 2 - Active Directory Authentication to Remote SQL Server](xref:ccm-service#scenario-two) -* [Scenario 3 - SQL Server Authentication to Local SQL Server](xref:ccm-service#scenario-three) -* [Scenario 4 - SQL Server Authentication to Remote SQL Server](xref:ccm-service#scenario-four) - - - -::::{.tab-content .text-bg-body-secondary .p-3 .mb-3 .border-start .border-end .border-bottom .rounded-bottom} -:::{.tab-pane .fade .show .active #scenario-one role=tabpanel aria-labelledby=scenario-one-tab} - -#### Windows Authentication to Local SQL Server - -Monolithic - you have set up the [database](xref:ccm-database) to use Windows Authentication (or Mixed Mode Authentication). You wish to use a local Windows account to connect to the local database. - -##### Specify User - -```powershell -choco install chocolatey-management-service -y --package-parameters="'/ConnectionString:Server=;Database=ChocolateyManagement;Trusted_Connection=True; /Username:'" --package-parameters-sensitive="'/Password:'" -``` - -> :choco-warning: **WARNING** -> -> Please ensure the user `` has been given `db_datareader` and `db_datawriter` access to the database. See [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - ---- - -##### `ChocolateyLocalAdmin` User - -```powershell -choco install chocolatey-management-service -y --package-parameters="'/ConnectionString:Server=;Database=ChocolateyManagement;Trusted_Connection=True;'" -``` - -> :choco-warning: **WARNING** -> -> Please ensure the user `ChocolateyLocalAdmin` has been given `db_datareader` and `db_datawriter` access to the database. See [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - -> :choco-info: **NOTE** -> -> Note the connection string doesn't include credentials. That's because Windows Authentication for SQL Server uses the context of what is running it and why the service itself needs the right user/password. - -::: -:::{.tab-pane .fade #scenario-two role=tabpanel aria-labelledby=scenario-two-tab} - -#### Active Directory Authentication to Remote SQL Server - -Split - you have set up the [database](xref:ccm-database) to use Windows Authentication (or Mixed Mode Authentication). You wish to use an Active Directory account to connect to an existing SQL instance. - -```powershell -choco install chocolatey-management-service -y --package-parameters="'/ConnectionString:Server=;Database=ChocolateyManagement;Trusted_Connection=True; /Username:'" --package-parameters-sensitive="'/Password:'" -``` - -> :choco-warning: **WARNING** -> -> Please ensure the user `` has been given `db_datareader` and `db_datawriter` access to the database. See [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - -> :choco-info: **NOTE** -> -> Note the connection string doesn't include credentials. That's because Windows Authentication for SQL Server uses the context of what is running it and why the service itself needs the right user/password. - -::: -:::{.tab-pane .fade #scenario-three role=tabpanel aria-labelledby=scenario-three-tab} - -#### SQL Server Authentication to Local SQL Server - -Monolithic - you are installing the management service on the same machine as a SQL Server Express instance. You likely have a smaller environment where you have up to 1,000 machines. You have set up the [database](xref:ccm-database) to use Mixed Mode Authentication. - -##### Licensed SQL Server - -```powershell -choco install chocolatey-management-service -y --package-parameters-sensitive="'/ConnectionString:Server=Localhost;Database=ChocolateyManagement;User ID=ChocoUser;Password=Ch0c0R0cks;'" -``` - -> :choco-warning: **WARNING** -> -> Please ensure the login has been given `db_datareader` and `db_datawriter` access to the database. See [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - ---- - -##### SQL Server Express - -```powershell -choco install chocolatey-management-service -y --package-parameters-sensitive="'/ConnectionString:Server=Localhost\SQLEXPRESS;Database=ChocolateyManagement;User ID=ChocoUser;Password=Ch0c0R0cks;'" -``` - -> :choco-warning: **WARNING** -> -> Please ensure the login has been given `db_datareader` and `db_datawriter` access to the database. See [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - -::: -:::{.tab-pane .fade #scenario-four role=tabpanel aria-labelledby=scenario-four-tab} - -#### SQL Server Authentication to Remote SQL Server - -Split - you are installing the management service(s) on a server, and targeting an existing SQL Server instance in your organization. You have set up the [database](xref:ccm-database) to use Mixed Mode Authentication. - -```powershell -choco install chocolatey-management-service -y --package-parameters-sensitive="'/ConnectionString:Server=;Database=ChocolateyManagement;User ID=ChocoUser;Password=Ch0c0R0cks;'" -``` - -> :choco-warning: **WARNING** -> -> Please ensure the login has been given `db_datareader` and `db_datawriter` access to the database. See [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - -::: -:::: - -## Step 3: Verify Installation - -The `chocolatey-management-service` is responsible for making a number of changes to your system. A successful installation of this package can be verified by: - -* Open the services snap-in (services.msc) and check for the presence of the `Chocolatey Management Service` which should be in the "Started" state. -* The installation folder for `chocolatey-management-service` is at `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service`. -* Open the Service log file located at `$env:ChocolateyInstall\logs\ccm-service.log` and verify that there are no recently reported errors. If you are on a version of Chocolatey Central Management prior to 0.2.0, the log will be located at `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\logs\chocolatey.service.host.log`. - -## FAQ - -### Why is the Chocolatey Central Management Service not marked as 'Stopped' when there is an error during its execution? - -By default, all exceptions that occur within the Chocolatey Central Management Service are logged to the applications log file (ccm-service.log). However, these exceptions do not result in actually physically stopping the service. -If an exception is thrown within the application, and you checked the Chocolatey Central Management Service in the Windows Services snap-in, you would still see that the service is running. -Due to the nature of how exceptions occur within the Chocolatey Central Management Service, this is normally perfectly fine since operations are attempted again at a later date. -There are occasions, for example when something in the `appsettings.json` file has been misconfigured, that an exception can be thrown and the service doesn't start up correctly, but it is still marked as Running. -This situation can occur with any version of Chocolatey Central Management up to and including v0.6.2, but it is something that we are looking to address in a future release. - -### What is the minimum required configuration for the `appsettings.json` file? - -As of Chocolatey Central Management v0.6.2, the default configuration values in the `appsettings.json` for the Chocolatey Central Management service are: - -```json -{ - "ConnectionStrings": { - "Default": "Server=; Database=ChocolateyManagement; Trusted_Connection=True;" - }, - "CertificateThumbprint": "" -} -``` - -> :choco-info: **NOTE** -> -> This file will usually be condensed into a single line, with the values encrypted. - -If these values are removed or incorrect, the Chocolatey Central Management service may fail to start. -To correct this, ensure all configuration is present and correct and then restart the Chocolatey Central Management service. - -```powershell -Get-Service -Name chocolatey-central-management | Restart-Service -``` - -### How can we increase the level of logging for Chocolatey Central Management? - -This can be done by changing the level value, which should be currently INFO, to use DEBUG, as per the following: - -```xml - - - - - -``` - -In the following files: - -* `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\log4net.config`. If you are on a version less than 0.2.0, then it will be in `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\chocolatey-central-management.exe.config`. -* `$env:ChocolateyInstall\lib\chocolatey-agent\tools\service\chocolatey-agent.exe.config` - -When the value is changed, the services may also need restarted. - -### How can we view what SSL registrations have been made by the installation of chocolatey-management-service? - -By default, the installation of the `chocolatey-management-service` package will register a single `netsh` binding between a self-signed certificate (created at the point of installation) and port 24020. This can be verified using the following command: - -```powershell -netsh http show sslcert -``` - ->:choco-info: **NOTE** -> ->Starting with Chocolatey Central Management 0.6.0, `netsh` bindings are no longer created during the installation of the Chocolatey Central Management Service package. On installing the 0.6.0 Chocolatey Central Management Service package, any existing `netsh` bindings that were created specifically for Chocolatey Central Management usage will be removed. - -### How can we remove a `netsh` binding that has been created? - -If you need to remove a `netsh` binding, you can do that using the following command: - -```powershell -netsh http delete sslcert ipport=0.0.0.0: -``` - -> :choco-info: **NOTE** -> -> Here, `` should be replaced with the Port Number that has been registered. -> ->Starting with Chocolatey Central Management 0.6.0, `netsh` bindings are no longer created during the installation of the Chocolatey Central Management Service package. On installing the 0.6.0 Chocolatey Central Management Service package, any existing `netsh` bindings that were created specifically for Chocolatey Central Management usage will be removed. - -### Can we manually create an SSL binding? - -If required, it is possible to manually create a `netsh` binding. This is done using the following command: - -```powershell -netsh http add sslcert ipport=0.0.0.0: certhash= appid={} -``` - -> :choco-info: **NOTE** -> -> Here, `` should be replaced with the Port Number to be used for the registration. `` should be replaced with the thumbprint for the certificate that is to be used for the registration. `` should be replaced with a random guid in the following format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` -> ->Starting with Chocolatey Central Management 0.6.0, `netsh` bindings are no longer created during the installation of the Chocolatey Central Management Service package. On installing the 0.6.0 Chocolatey Central Management Service package, any existing `netsh` bindings that were created specifically for Chocolatey Central Management usage will be removed. - -### Can we install the Chocolatey Central Management Service behind a load balancer? - -Unfortunately, this is not a supported scenario. If you are trying to load balance requests to the Chocolatey Central Management service, you should install multiple instances on multiple machines and point clients explicitly to an instance so they can work together. If you are trying to load balance other things on a machine and the Chocolatey Central Management service just happens to be there (like with QDE), move the Chocolatey Central Management service to a different machine or allow direct connections to the box for Chocolatey Central Management. - -> :choco-info: **NOTE** -> -> If you are an expert in managing X509 certificates with load balancing, you can certainly set this up, but if you can't get it to work, move to a supported scenario. The Support team will tell you the same. - -### We want to set up the Chocolatey Central Management service to use a domain account that will have local admin privileges on each box. Can we do this? - -Yes, absolutely. You will pass those credentials through at install/upgrade time, and you will also want to turn on the feature `useRememberedArgumentsForUpgrades` (see [configuration](xref:configuration#features)) so that future upgrades will have that information available. The remembered arguments are stored encrypted on the box (and that encryption is reversible so you may opt to pass that information each time). - -* `/Username`: - provide username - instead of using the default 'ChocolateyLocalAdmin' user. This user should be a local Administrator. -* `/Password`: - optional password for the user. -* `/EnterPassword` - receive the password at runtime as a secure string - -You would pass something like `choco install chocolatey-management-service -y --params="'/Username:domain\account /EnterPassword'"` to securely pass the password at runtime. You could also run `choco install chocolatey-management-service -y --params="'/Username:'" --package-parameters-sensitive="'/Password:'"` (or do it as part of `choco upgrade`). - -### Is the password stored anywhere? - -No, that would reduce the security of the password. It exists in memory long enough to set the value on the user and the service and then it is cleared. - -There is no storage of the password anywhere other than how Windows stores passwords. - -### We are going to use our own account with a rotating password. When we rotate the password for the account that we use for the Chocolatey Central Management Service, what do we need to do? - -Like with any service that uses rotating passwords, you will need to redeploy the service or go into the Services Management console and update the password. As it is much faster to deploy out that update, you can do something like `choco upgrade chocolatey-management-service -y --params="'/Username:domain\account'" --package-parameters-sensitive="'/Password:newpassword'" --force` (the `--force` ensures the code is redeployed). - -### Tell me more about the Chocolatey managed password. - -So you've seen from above that - -* It is 32 characters long. -* It uses uppercase, lowercase, numbers, and symbols to meet very stringent complexity requirements. -* The password is different for every machine. -* Due to the way that it is generated, it is completely unguessable. -* No one at Chocolatey Software could even tell you what the password is for a particular machine without local access. - -Chocolatey uses something unique about each system, along with an encrypted value in the licensed code base to generate the base password. It then makes some other changes to ensure that the password meets complexity requirements. We won't give you the full algorithm of how the password is generated as knowing the algorithm would be a security issue. Like having a partial picture of a key; you could start working on how to break in. Unlike a picture of a key, even knowing the full algorithm doesn't get you everything you need as you would require local access to **each** machine to determine the password for **each** machine. - -### Is the managed password stored or logged anywhere? - -No, that would reduce the security of the password. It exists in memory long enough to set the value on the user and the service and then it is cleared. - -There is no storage of the password anywhere other than how Windows stores passwords. - -### Is the managed password the same on every machine? - -No, a different password is created for every machine at deployment. - -### How would someone potentially get access to the managed password? - -The Chocolatey licensed code base is encrypted, so only people that work at Chocolatey Software would be able to determine the password for a particular box (just that one) **IF** they have local access to that box. Even with all of the information and the algorithm, it's still going to take our folks a while to determine the password. That gets them access to one machine. Of course, Chocolatey folks are not going to do this for obvious reasons. - -Let's realize this to its full potential - If someone were able to hack the Chocolatey licensed codebase, they would be able to determine the full password algorithm. Then they'd also need to hack into your infrastructure and get local access to every box that they wanted to get the Chocolatey-managed password so they could get admin access to just that box. Taking this out a bit further, it's reasonable to assume that if someone has hacked into your infrastructure, it's highly unlikely they are going to be using a non-Administrator account to get local access to a box so they can get the password for an Administrator account for just that one box. It's more likely they would would already have a local admin account for the boxes they are attacking, and are likely to seek other attack vectors that are much less sophisticated. - -### Do you rotate the managed password on a schedule? - -We are looking to do this in a future release. We may make the schedule configurable. - -### Can I take advantage of Chocolatey managed passwords with my own Windows services? - -Yes, absolutely. If you use Chocolatey For Business's PowerShell Windows Services code, you will be able to install services and have Chocolatey manage the password for those as well. - -### What is the Chocolatey Central Management Component Compatibility Matrix? - -Chocolatey Central Management has specific compatibility requirements with quite a few moving parts. It is important to understand that there are some Chocolatey Agent versions that may not be able to communicate with some versions of Chocolatey Central Management and vice versa. Please see the [Chocolatey Central Management Component Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix) for details. - -### I entered incorrect database details on install. Do I need to reinstall to fix that? - -It depends. You can simply go to the `appsettings.json` file and adjust the connection string to be plaintext. It will remain in plaintext though (at least until upgrade), so if you have actual password details you need to keep secure, you should do a force installation using the `--force` parameter. - -1. The file is located at `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\appsettings.json`. -1. You would open that up in an editor and modify the `"Default"` connection string. -1. It would look something like the following (adjust the connection string as necessary): - -```json -{ - "ConnectionStrings": { - "Default": "Server=; Database=ChocolateyManagement; Trusted_Connection=True;" - } -} -``` - -1. You may find it all on a single line in the file, and that is okay. -1. Restart the service by running the following from an admin powershell session: `Get-Service chocolatey-management-service | Stop-Service; Get-Service chocolatey-management-service | Start-Service` - -> :choco-warning: **WARNING** -> -> Do not put `sec:` or `secure-` at the start (prefix) of any values that you are adding/modifying directly. That tells Chocolatey components they are encrypted and it will attempt to decrypt them for use. If that is done incorrectly, it will cause things to crash. - -### Can we use an account for the service that is not a local Administrator? - -No. This is not a supported scenario. The installation will attempt to ensure that the user becomes an Administrator if they are not, in addition to `Logon as Service` and `Logon as Batch` privileges. - -### Where is the management service installed? - -The installation folder for `chocolatey-management-service` is at `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service`. - -___ - -## Common Errors and Resolutions - -### Cannot convert the "System.Object[]" value of type "System.Object[]" to type "System.Int32". - -You may see this error message when attempting to install version 0.6.0 of the `chocolatey-management-service` package. - -Please see [Licensed Issue #242](https://github.com/chocolatey/chocolatey-licensed-issues/issues/242) for details on a workaround that can be used. This bug will be addressed in the 0.6.1 release of Chocolatey Central Management. - -### Agents are unable to communicate with Chocolatey Central Management Service and the Chocolatey Central Management service log shows "Unable to start Kestrel". - -This is a known issue with Chocolatey Central Management v0.6.0 and v0.6.1 due to changes in how the Chocolatey Central Management service is hosted. -`netsh` bindings are no longer required for the Chocolatey Central Management service, and you may also notice the bindings for the Chocolatey Central Management service removed during upgrade. -The identifying symptom of this issue is the following in the Chocolatey Central Management service log file: - -```log -[FATAL] Microsoft.AspNetCore.Server.Kestrel (0): Unable to start Kestrel -``` - -In these versions, the best workaround is to ensure that your `LocalMachine\TrustedPeople` certificate store contains only one certificate with a DNS name that matches the Chocolatey Central Management service URL setting in your `chocolatey.config` file, and that this certificate has the `ServerAuthentication` usage applied to it. - -Starting in v0.6.2, it is possible to configure the Chocolatey Central Management service to select a specific certificate to use. -The Chocolatey Central Management service log file error will also now contain slightly more information, looking something like this: - -```powershell -[FATAL] ChocolateyServiceManagementTask: Microsoft.AspNetCore.Server.Kestrel [0] -Unable to start Kestrel. -System.InvalidOperationException: Certificate 3edebdfee63b57b0a0a12a079ed8da791da03ba7 cannot be used as an SSL server certificate. It has an Extended Key Usage extension but the usages do not include Server Authentication (OID 1.3.6.1.5.5.7.3.1). -``` - -You may also receive a differently-worded error if the certificate used by the Chocolatey Central Management service in the `LocalMachine\TrustedPeople` store is removed. - -Starting in Chocolatey Central Management v0.6.2, the Chocolatey Central Management Service package will attempt to select an appropriate certificate during installation, and store the thumbprint in the `appsettings.json` file. -You can also specify the thumbprint for the certificate to use as the `/CertificateThumbprint` package parameter during installation or upgrade. - -If you need to change the certificate you're using after installation, you can modify the entry in the `appsettings.json` file for the Chocolatey Central Management service, shown below. - -```json -{ - "ConnectionStrings": { - "Default": "Server=; Database=ChocolateyManagement; Trusted_Connection=True;" - }, - "CertificateThumbprint": "" -} -``` - -Altering the `CertificateThumbprint` value will cause the Chocolatey Central Management service to select the corresponding certificate from the `LocalMachine\TrustedPeople` store instead. -You will need to restart the Chocolatey Central Management service after changing this value for it to take effect. - -```powershell -Get-Service -Name chocolatey-central-management | Restart-Service -``` - -### Chocolatey Agent Service is unable to communicate with Chocolatey Central Management Service. - -There is a known issue with the beta release of Chocolatey Central Management where an inconsistent Port Number is used between these two services. One used 24020 and the other used 24040. The correct default Port Number is 24020, and this is used in the 0.1.0 release of Chocolatey Central Management. If required, the Port Number can be explicitly set during the installation of the Chocolatey Central Management packages using the following option when installing `chocolatey-management-service`: - -```powershell ---params="'/PortNumber=24020'" -``` - -### Unable to report computer information to Chocolatey Central Management. - -You may see messaging like the following in the `chocolatey-agent.log`: - -```sh -[INFO ] - Creating secure channel to https://ccmserver:24020/ChocolateyManagementService ahead of CCM check-in... -[ERROR] - Unable to report computer information to CCM.: - The message with Action 'http://tempuri.org/IChocolateyManagementService/report_computer_information' cannot be - processed at the receiver, due to a ContractFilter mismatch at the EndpointDispatcher. This may be because of either a - contract mismatch (mismatched Actions between sender and receiver) or a binding/security mismatch between the sender - and the receiver. Check that sender and receiver have the same contract and the same binding (including security - requirements, e.g. Message, Transport, None). -``` - -This is due to having a Chocolatey Agent that is v0.10.0+ versus an older Chocolatey Central Management Service (< v0.2.0). Newer agents are incompatible because they use newer and more secure methods of communication. Please upgrade Chocolatey Central Management to v0.2.0+ at your earliest convenience. Or if you are on Chocolatey Central Management v0.3.0+, your agents need to be on v0.11.0+. Please refer to the [Chocolatey Central Management Component Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix). - -### Unable to check for deployments from Chocolatey Central Management. - -This will provide similar messaging as the above. The fix is the same, upgrade Chocolatey Central Management to v0.2.0+. Or if you are on Chocolatey Central Management v0.3.0+, your agents need to be on v0.11.0+. Please refer to the [Chocolatey Central Management Component Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix). You may need to be on at least v0.3.0 and agents on v0.11.0+. If you are experiencing improper passphrase issues noted below, it means you need to likely upgrade to v0.3.0+ / v0.11.0 across your infrastructure. - -### We are seeing the error "attempted to call report_computer_information with an improper passphrase" in the Chocolatey Central Management service log. - -If you are in the Chocolatey Central Management service logs, you may see the above error. This is a bug that was found with the communication of Chocolatey Central Management v0.2.0 and Chocolatey Agent v0.10.0. That was resolved in Chocolatey Central Management v0.3.0 and Chocolatey Agent v0.11.0. Please see the [Chocolatey Central Management Component Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix) and [Licensed Issue #152](https://github.com/chocolatey/chocolatey-licensed-issues/issues/152) for more details. - -### The client reports successful check-in, but nothing is showing up in Chocolatey Central Management. - -You need to check the Chocolatey Central Management service logs. The agent will always report success when it communicates with the service successfully. The service may reject what it receives, but due to security settings, it won't tell the client about that. - -The logs are located at `$env:ChocolateyInstall\logs\ccm-service.log`. If you are on a version of Chocolatey Central Management prior to 0.2.0, the log will be located at `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\logs\chocolatey.service.host.log`. - -### A parameter cannot be found that matches parameter name KeyUsage. - -This is a known issue with the beta release of Chocolatey Central Management regarding the creation of a self-signed certificate. You may see the error: - -`A parameter cannot be found that matches parameter name KeyUsage` - -This happens when installing Chocolatey Central Management on a machine that has PowerShell 4 or earlier. This is corrected in the 0.1.0 release of Chocolatey Central Management. - -To work around this issue, you can use the following script to manually create a self-signed certificate, which will then be used to continue the installation: - -```powershell -$hostName = [System.Net.Dns]::GetHostName() -$domainName = [System.Net.NetworkInformation.IPGlobalProperties]::GetIPGlobalProperties().DomainName - -if(-Not $hostName.endswith($domainName)) { - $hostName += "." + $domainName -} - -$certificateDnsName = $hostName - -$newCert = New-SelfSignedCertificate -CertStoreLocation cert:\LocalMachine\My -DnsName $certificateDnsName - -# move the certificate to 'TrustedPeople' -$certPath = Get-ChildItem -Path 'Cert:\\LocalMachine\\My' | Where-Object subject -like "*$certificateDnsName" -$null = Move-Item -Path $certPath.PsPath -Destination 'Cert:\\LocalMachine\\TrustedPeople' -``` - -### The term 'Install-ChocolateyAppSettingsJsonFile' is not recognized as the name of a cmdlet, function, script file, or operable program. - -In the beta version of the Chocolatey Licensed Extension, there was a cmdlet named `Install-ChocolateyAppSettingsJsonFile` and this was used in the 0.1.0-beta-20181009 release of the Chocolatey Central Management components. In the final released version of the Chocolatey Licensed Extension, this was renamed to `Install-AppSettingsJsonFile`. - -As a result, the Chocolatey Central Management beta no longer works with the released version of Chocolatey Licensed Extension. This will be corrected once the next release of the Chocolatey Central Management components is completed. - -### Cannot process command because of one or more missing mandatory parameters: FilePath. - -During the creation of Chocolatey Central Management, some additional PowerShell cmdlets were created, and these are installed as part of the Chocolatey Licensed Extension package. These cmdlets went through a number of iterations, and as a result, different combinations of Chocolatey Central Management packages were incompatible with the Chocolatey Licensed Extension package, resulting in the error: - -`Cannot process command because of one or more missing mandatory parameters: FilePath` - -The guidance in this case to update to the latest versions of all packages where the situation should be addressed. - -### The remote server returned an unexpected response: (413) Request Entity Too Large. - -When reporting a larger number of packages (approximately 200), this error may be reported. This is due to the size of the information, in bytes, being too large to send between the Chocolatey Agent Service and the Chocolatey Central Management Service. This has been identified as a [bug](https://github.com/chocolatey/chocolatey-licensed-issues/issues/95), which is due to be corrected in version 0.1.1 of Chocolatey Central Management. - -### ERROR: Cannot index into a null array. - -This error can be reported when installing the Chocolatey Central Management Service. This can happen depending on the `netsh` bindings that are currently present on the machine that the Chocolatey Central Management service is being installed on. If, for example, you have enabled SNI on a website on the machine that you are installing onto, then this error may occur. This has been identified as a [bug](https://github.com/chocolatey/chocolatey-licensed-issues/issues/96), which is due to be corrected in version 0.1.1 of Chocolatey Central Management. - -This could also be when you are providing an existing certificate - this was identified as a [bug](https://github.com/chocolatey/chocolatey-licensed-issues/issues/143) and was fixed in Chocolatey Central Management v0.2.0. - -There is a known issue with Chocolatey Central Management v.0.3.0 affecting at least French machines. Please reach out to Support if you are experiencing this (run `choco support` for options). - -### The new license is not being picked up. - -You need to restart services and Chocolatey Central Management web to pick up the license. Here's a handy script: - -```powershell -Get-Service chocolatey-* | Stop-Service -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Get-Service chocolatey-* | Start-Service -``` - -### Failed to generate a user instance of SQL Server due to failure in retrieving the user's local application data path. - -You may see the following: "System.Data.SqlClient.SqlException (0x80131904): Failed to generate a user instance of SQL Server due to failure in retrieving the user's local application data path. Please make sure the user has a local user profile on the computer. The connection will be closed." - -This means you are attempting to attach a Local DB file as part of your connection. **This is an invalid scenario.** This could also mean that there is something wrong with your connection strings format in the `appsettings.json` file. - -### System.ServiceModel.AddressAccessDeniedException HTTP could not register URL. - -You may see the following: `System.ServiceModel.AddressAccessDeniedException: HTTP could not register URL https://+:24020/ChocolateyManagementService/. Your process does not have access rights to this namespace (see http://go.microsoft.com/fwlink/?LinkId=70353 for details). ---> System.Net.HttpListenerException: Access is denied` - -You are attempting to set up a user that is not in the local Administrators group with the Chocolatey Central Management Service. **This is not a supported scenario.** - -Please refer to the [Chocolatey Central Management Service Windows Account Considerations](xref:ccm-service#chocolatey-central-management-service-windows-account-considerations) and select an option that works best for your organization. - -[Central Management Setup](xref:ccm-setup) | [Chocolatey Central Management](xref:central-management) - -### Error 1053: The service did not respond to the start or control request in a timely fashion. - -If the Chocolatey Central Management Service is not able to be started due to "Error 1053: The service did not respond to the start or control request in a timely fashion.", it is likely caused due to no compatible versions of dotnet aspnetruntime not being installed. - -The installed runtimes can be listed with `dotnet --list-runtimes`. Ensure that a 6.x.x version of Microsoft.AspNetCore.App is listed. If there is not a version listed, reinstall `dotnet-6.0-aspnetruntime`. - -There is a known issue with the aspnetcoremodule-v2 installer that will uninstall the aspnetruntime on upgrade, which may be the root cause for this missing runtime. https://github.com/dotnetcore-chocolatey/dotnetcore-chocolateypackages/issues/64 \ No newline at end of file diff --git a/input/en-us/central-management/setup/upgrade.md b/input/en-us/central-management/setup/upgrade.md deleted file mode 100644 index 86336a1469..0000000000 --- a/input/en-us/central-management/setup/upgrade.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -Order: 50 -xref: ccm-upgrade -Title: Upgrade -Description: How to upgrade CCM -RedirectFrom: docs/central-management-setup-upgrade ---- - -This will guide us through upgrading an existing Chocolatey Central Management installation to newer versions. - -> :choco-info: **NOTE** -> -> Looking for installation instructions? See [Central Management Setup](xref:ccm-setup). - -> :choco-warning: **WARNING** -> -> - Unless otherwise noted, please follow these steps in **exact** order. These steps build on each other and need to be completed in order. -> - All deployed components of the CCM packages should **always** be the **SAME VERSION**. The only time you should not have this is when you are in a state of upgrading and that transition time should be quite short. - -## Step 0: Backup Your Current CCM Environment - -We suggest you go through and take a snapshot of your CCM VM before proceeding with an upgrade. If taking a snapshot is not an option, at a bare minimum we recommend creating a local backup of the CentralManagement SQL Database and backing up your appsettings.json file located at `C:\tools\chocolatey-management-web\appsettings.json`. - -## Step 1: Download Latest Packages - -> :choco-info: **NOTE** -> -> Make sure you have read over the [CCM Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix) prior to starting internalization as this will save you some headaches. - -Similar to how we internalized in [Setup - Internalize Packages](xref:ccm-setup#step-1-internalize-packages), we need to get the latest editions of everything compatible. Be sure that the versions of packages you have match up with the [Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix). - -```powershell -# To run this, you need Chocolatey for Business installed (chocolatey / chocolatey.extension). - -# Update the values and remove the < > -$YourInternalRepositoryPushUrl = '' -$YourInternalRepositoryApiKey = '' -# You get this from the chocolatey.license.xml file: -$YourBusinessLicenseGuid = '' - -# Download Chocolatey community related dependencies, internalization necessary -choco download dotnet-6.0-runtime dotnet-6.0-aspnetruntime dotnet-aspnetcoremodule-v2 --source="'https://community.chocolatey.org/api/v2/'" --internalize --output-directory="'C:\packages'" - -# Download Licensed Packages -## DO NOT RUN WITH `--internalize` and `--internalize-all-urls` - see https://github.com/chocolatey/chocolatey-licensed-issues/issues/155 -choco download chocolatey chocolatey-agent chocolatey.extension chocolatey-management-database chocolatey-management-service chocolatey-management-web --source="'https://licensedpackages.chocolatey.org/api/v2/'" --ignore-dependencies --output-directory="'C:\packages'" --user="'user'" --password="'$YourBusinessLicenseGuid'" - -# Push all downloaded packages to your internal repository -Get-ChildItem C:\packages -Recurse -Filter *.nupkg | Foreach-Object { choco push $_.Fullname --source="'$YourInternalRepositoryPushUrl'" --api-key="'$YourInternalRepositoryApiKey'"} -``` - -## Step 2: Upgrade Central Management Database - -> :choco-info: **NOTE** -> -> Please see [Central Management Database Setup](xref:ccm-database) for details about all arguments that can be passed and set. - -```powershell -choco upgrade chocolatey-management-database -y -``` - -> :choco-warning: **WARNING** -> -> If you are using QDE and receive an error about deserializing and padding, see the resolution below. - -## Step 3: Setup Central Management Windows Service(s) - -> :choco-info: **NOTE** -> -> Please see [Central Management Service Setup](xref:ccm-service) for details about all arguments that can be passed and set. - -```powershell -choco upgrade chocolatey-management-service -y -``` - -> :choco-warning: **WARNING** -> -> - If you passed non-default options for any of the following: -> - `/Username:` / `/Password:` / `/EnterPassword` -> - `/PortNumber:` -> You **will need to pass those items again** for upgrades in current releases of CCM. -> - If you passed a non-default option for the `/CertificateDnsName:` / `/CertificateThumbprint:`, you **may need to pass those items again** under the following conditions: -> - Your certificate's DNS name does not match `*`(a certificate that at least starts with the hostname). - -> :choco-info: **NOTE** -> -> Database details that have not changed will not need to be passed. - -There may be additional (new) things you will want to configure. Please see [Central Management Service Setup](xref:ccm-service) for details. - -## Step 4: Setup Central Management Website - -> :choco-info: **NOTE** -> -> Please see [Central Management Web Setup](xref:ccm-website) for details about all arguments that can be passed and set. - -```powershell -choco upgrade chocolatey-management-web -y -``` - -> :choco-warning: **WARNING** -> -> You may need to adjust permissions/roles for your user if not using the default `ccmadmin` account. Please see the roles and permissions your account has versus what is available in `Administration -> Users`. - -## Step 5: Upgrade Agent Machines - -> :choco-info: **NOTE** -> -> Please see [Central Management Client Setup](xref:ccm-client) for details about all arguments that can be passed and set. - -```powershell -choco upgrade chocolatey-agent -y -``` - -There may be additional (new) things you will want to configure. Please see [Central Management Client Setup](xref:ccm-client) for details. - -> :choco-info: **NOTE** -> -> This could include the agent(s) on the CCM machine(s). - -> :choco-warning: **WARNING** -> -> The Chocolatey Agent installed on the same machine that has the CCM Service installed will share the `centralManagementServiceUrl` setting, so that agent can only report into that CCM Service. - -### New Deployments Feature Example - -As an example, configuring using Deployments would have the folllowing: - -```powershell -# Requires Chocolatey Licensed Extension v2.1.0+, Chocolatey-Agent v0.10.0+, and Chocolatey Central Management v0.2.0+: -choco feature enable --name="'useChocolateyCentralManagementDeployments'" -``` - -> :choco-warning: **WARNING** -> -> As these features have security considerations (it is enabling cross-machine communication), they must be turned on explicitly. -> If you decide you want to open this up for over the internet communication, you should also set `centralManagementClientCommunicationSaltAdditivePassword` and `centralManagementServiceCommunicationSaltAdditivePassword`. -> For more in-depth configuration options and settings for your endpoints, you can view the [CCM Client Setup page](xref:ccm-client) - -## FAQs - -### Can I simply upgrade all three CCM packages in the same command? - -We strongly advise against it as there is an explicit order that things must be upgraded in. Since CCM components can be installed on separate machines, there is no explicit dependency that can be taken. Just note that running - -```powershell -# !!!DO NOT DO THIS!!! -# choco upgrade chocolatey-management-database chocolatey-management-service chocolatey-management-web -y -``` - -when you have everything on the same box may work, but it may not. Please follow the steps here for best success. - -### If I update the license file, do I need to restart my services and web? - -Yes, you do need to restart the agents, the service, and the web to pick up the license. Here's a script to handle that: - -```powershell -# For CCM versions older than v0.6.0 -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force - -# For CCM version 0.6.0 and 0.6.1 -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force -Stop-Website -Name ChocolateyCentralManagement -Restart-WebAppPool -Name ChocolateyCentralManagement -Start-Website -Name ChocolateyCentralManagement - -# For CCM v0.6.2 and up -Stop-Website -Name ChocolateyCentralManagement -Restart-WebAppPool -Name ChocolateyCentralManagement -Start-Website -Name ChocolateyCentralManagement - -# Restart Chocolatey Agent and/or CCM service (all versions) -Get-Service chocolatey-* | Restart-Service -``` - -### Can I use Chocolatey Deployments to upgrade CCM based components? - -Likely you absolutely can, just keep in mind that there may be a specific ordering in how you would upgrade everything and adhere to that order. In some instances, you may need to upgrade agents first, then CCM components as once CCM is upgraded it may not be able to talk to the agents. However agents will stop being able to talk to CCM for a small period of time while you are upgrading CCM, but then things will start working again. - -### Why does the chocolatey-management-web package upgrade when I upgrade the chocolatey-management-service package? - -> :choco-warning: **WARNING** -> -> This only applies to version of CCM _after_ 0.6.0 and _before_ 0.9.0. - -When you run the upgrade of the chocolatey-management-service package from a computer that has all the CCM packages installed, you may not expect the chocolatey-management-web package to also be upgraded. - -This happens due to the bounded version numbers that are in place for the service and web packages. Starting with 0.6.0, both the service and web packages have the following dependencies: - -```xml - - -``` - -Prior to 0.6.0, only the chocolatey-management-web package had the following dependencies: - -```xml - - -``` - -You will notice that there is an upper bounded version number of 3.0.0, meaning that Chocolatey won't allow a version higher than 3.0.0 of these dependencies to be installed. - -In the new 0.6.0 packages for CCM, the upper bounded version number has changed to 4.0.0. As a result, when running the upgrade command for the chocolatey-management-service package, Chocolatey will also want to install a 4.x.x version of the dependencies, but this _isn't_ allowed due to the constraints on the installed earlier version of the chocolatey-management-web package. To remedy this, Chocolatey is able to find a newer version of the chocolatey-management-web package which does fit within these new constraints, and therefore the chocolatey-management-web package is also upgraded. - -## Common Errors and Resolutions - -### ERROR: There was an error deserializing the requested JSON file: C:\ProgramData\chocolatey\lib\chocolatey-management-database\tools\app\appsettings.json Padding is invalid and cannot be removed. - -This means that the Chocolatey Unique Machine GUID has been changed since you installed the database, as you might see with some versions of QDE (which might be corrected in a version you have.) - -In that case you should run the following script: - -```powershell -Remove-Item -Force -Path "$env:ChocolateyInstall\lib\chocolatey-management-database\tools\app\appsettings.json" -ErrorAction SilentlyContinue -choco upgrade chocolatey-management-database -y --package-parameters="'/SqlServerInstance:localhost\SQLEXPRESS'" --source="'c:\choco-setup\packages'" -``` - -### When I upgrade the website, it wipes out any http port bindings I created - -This was an issue in releases prior to upgrading to CCM v0.3.0 - see . -If you run into this, please recreate the bindings again. - -### ERROR: The term 'Install-SettingsJsonFile' is not recognized as the name of a cmdlet, function, script file, or operable program. - -This is . - -There are two workarounds noted: - -- Delete the appsettings.json file prior to upgrade -- Do not pass database details if they have not changed during upgrade. - -[Central Management Setup](xref:ccm-setup) | [Chocolatey Central Management](xref:central-management) - -### When upgrading the CCM website, Chocolatey reports a lot of errors about files being locked, and the CCM website does not function after the upgrade - -This is a known issue for v0.6.0 and v0.6.1 releases, and is resolved as of v0.6.2. -The IIS hosting model changed as of v0.6.0 to use the in-process model, which alters how the website needs to be shut down and restarted. - -A quick workaround is to stop the CCM website manually before running the upgrade by running the following in an administrative Windows PowerShell session: - -```powershell -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force -PassThru -Stop-Website -Name ChocolateyCentralManagement -Stop-WebAppPool -Name ChocolateyCentralManagement -``` - -Once the upgrade process has completed, you can ensure the website is properly restarted by running: - -```powershell -Start-WebAppPool -Name ChocolateyCentralManagement -Start-Website -Name ChocolateyCentralManagement -``` diff --git a/input/en-us/central-management/setup/website.md b/input/en-us/central-management/setup/website.md deleted file mode 100644 index 2ee18a7323..0000000000 --- a/input/en-us/central-management/setup/website.md +++ /dev/null @@ -1,626 +0,0 @@ ---- -Order: 30 -xref: ccm-website -Title: Website -Description: Information on how to setup the CCM Website -RedirectFrom: docs/central-management-setup-web ---- - -This is the Chocolatey Central Management website that gives an API and a web layer to centrally manage information about your environment and manage endpoints with deployment tasks. - -> :choco-warning: **WARNING** -> -> Unless otherwise noted, please follow these steps in **exact** order. These steps build on each other and need to be completed in order. - -## Step 1: Complete Prerequisites - -> :choco-warning: **WARNING** -> -> The [database](xref:ccm-database) must be setup and available, along with [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - -* [High-level Requirements](xref:ccm-setup#high-level-requirements) -* PowerShell 5.1 -* IIS Set up and available -* dotnet-aspnetcoremodule-v2 version 16.0.23055 -* dotnet-6.0-runtime version 6.0.15 -* dotnet-6.0-aspnetruntime version 6.0.15 - -The Chocolatey Central Management Website is built on ASP.Net Core, and as such we need to ensure that it is installed on the server for proper function. Note that the codebase is currently locked to version `6.x.x` of these packages, and it is critical that you install these right, otherwise you will encounter errors. At the time of release, the most recent version of these packages was 6.0.5, though we recommend installing the latest versions of these packages. - -### Script for some prerequisites - -```powershell -choco install IIS-WebServer --source windowsfeatures --no-progress -y -choco install IIS-ApplicationInit --source windowsfeatures --no-progress -y -choco install dotnet-aspnetcoremodule-v2 --version 16.0.23055 --no-progress -y -choco install dotnet-6.0-runtime --version 6.0.15 --no-progress -y -choco install dotnet-6.0-aspnetruntime --version 6.0.15 --no-progress -y -``` - -## Step 2: Install Chocolatey Central Management Web Package - -> :choco-info: **NOTE** -> -> At this time we don't recommend opening internet access to Chocolatey Central Management web. However, if you choose to, you will want to set up SSL/TLS certificates to ensure communication is encrypted over the internet. - -### Package Parameters - -Note items with "`:`" mean a value should be provided. Items without are simply switches. - -* `/Username:` - Username that the IIS Web Application Pool will run under. Defaults to `IIS APPPOOL\ChocolateyCentralManagement`. If this is specified, you must also specify either `/Password` or `/EnterPassword`. - > :choco-info: **NOTE** - > - > This may require manual steps after install as well. See [Non-Default App Pool User Considerations](#non-default-app-pool-user-considerations). -* `/Password:` - Password for the user. Defaults to a Windows autogenerated secure password for the IIS AppPool. -* `/EnterPassword` - Receive the password at runtime as a secure string. Requires input at runtime whe installing/upgrading the package. -* `/ConnectionString:` - The SQL Server database connection string to be used to connect to the Chocolatey Central Management database. Defaults to default or explicit values for `/SqlServiceInstance` and `/Database`, along with Integrated Security (`Server=; Database=ChocolateyManagement; Trusted_Connection=True;`). The account should have `db_datareader`/`db_datawriter` access to the database ([data reader / data writer](https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/database-level-roles#fixed-database-roles)). -* `/SqlServerInstance:` - Instance name of the SQL Server database to connect to. Alternative to passing full connection string with `/ConnectionString`. Uses `/Database` (below) to build a connection string. Defaults to ``. -* `/Database:` - Name of the SQL Server database to use. Alternative to passing full connection string with `/ConnectionString`. Uses `/SqlServerInstance` (above) to build a connection string. Defaults to `ChocolateyManagement`. - -### IIS Settings - -This package creates the Chocolatey Central Management Website and Application Pool with the following defaults: - -* IIS Web Application Pool: **ChocolateyCentralManagement** - * enable32BitAppOnWin64: **True** - * managedPipelineMode: **Integrated** - * managedRuntimeVersion: <blank> - * startMode: **AlwaysRunning** - * processModel.idleTimeout: **0** - * recycling.periodicRestart.schedule: **Disabled** - * recycling.periodicRestart.time: **0** -* Website Name: **ChocolateyCentralManagement** - * PortBinding: **80** - * applicationDefaults.preloadEnabled: **True** - -### Non-Default App Pool User Considerations - -If you've used a specific username for the app pool, specified by `/Username:` or later added one manually to IIS settings, it's important to note that the installation procedure as of Chocolatey Central Management v0.3.0 does not currently set the following and they will need to be set manually. - -This includes (but may not be limited to): - -* User needs to be granted "Logon as batch" in local security policy. -* User needs to be given explicit Read/Execute rights (ACLs) to `c:\tools\chocolatey-management-web`. -* User needs to be given explicit Modify rights (ACLs) to `c:\tools\chocolatey-management-web\App_Data`. - -### Database Authentication Scenarios - -* [Scenario 1 - Windows Authentication to Local SQL Server](xref:ccm-website#scenario-one) -* [Scenario 2 - Active Directory Authentication to Remote SQL Server](xref:ccm-website#scenario-two) -* [Scenario 3 - SQL Server Authentication to Local SQL Server](xref:ccm-website#scenario-three) -* [Scenario 4 - SQL Server Authentication to Remote SQL Server](xref:ccm-website#scenario-four) - - - -::::{.tab-content .text-bg-body-secondary .p-3 .mb-3 .border-start .border-end .border-bottom .rounded-bottom} -:::{.tab-pane .fade .show .active #scenario-one role=tabpanel aria-labelledby=scenario-one-tab} - -#### Windows Authentication to Local SQL Server - -Monolithic - you have set up the [database](xref:ccm-database) to use Windows Authentication (or Mixed Mode Authentication). You wish to use a local Windows account to connect to the local database. - -##### Specify User - -```powershell -choco install chocolatey-management-web -y --package-parameters="'/ConnectionString:Server=;Database=ChocolateyManagement;Trusted_Connection=True; /Username:'" --package-parameters-sensitive="'/Password:'" -``` - -> :choco-warning: **WARNING** -> -> Please ensure the user `` has been given `db_datareader` and `db_datawriter` access to the database. See [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - ---- - -##### Default User (`IIS APPPOOL\ChocolateyCentralManagement`) - -```powershell -choco install chocolatey-management-web -y --package-parameters="'/ConnectionString:Server=;Database=ChocolateyManagement;Trusted_Connection=True;'" -``` - -> :choco-warning: **WARNING** -> -> Please ensure the user `IIS APPPOOL\ChocolateyCentralManagement` has been given `db_datareader` and `db_datawriter` access to the database. See [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - -> :choco-info: **NOTE** -> -> Note the connection string doesn't include credentials. That's because Windows Authentication for SQL Server uses the context of what is running it and why the service itself needs the right user/password. Whatever is running the IIS Application Pool is the user you need to ensure is in the database. - -::: -:::{.tab-pane .fade #scenario-two role=tabpanel aria-labelledby=scenario-two-tab} - -#### Active Directory Authentication to Local SQL Server - -Split - you have set up the [database](xref:ccm-database) to use Windows Authentication (or Mixed Mode Authentication). You wish to use an Active Directory account to connect to an existing SQL instance. - -```powershell -choco install chocolatey-management-web -y --package-parameters="'/ConnectionString:Server=;Database=ChocolateyManagement;Trusted_Connection=True; /Username:'" --package-parameters-sensitive="'/Password:'" -``` - -> :choco-info: **NOTE** -> -> Note the connection string doesn't include credentials. That's because Windows Authentication for SQL Server uses the context of what is running it and why the service itself needs the right user/password. In this case, whatever is running the IIS Application Pool is the user you need to ensure has access to the database. - -::: -:::{.tab-pane .fade #scenario-three role=tabpanel aria-labelledby=scenario-three-tab} - -#### SQL Server Authentication to Local SQL Server - -Monolithic - you are installing the management service on the same machine as a SQL Server Express instance. You likely have a smaller environment where you have up to 1,000 machines. You have set up the [database](xref:ccm-database) to use Mixed Mode Authentication. - -##### Licensed SQL Server - -```powershell -choco install chocolatey-management-web -y --package-parameters-sensitive="'/ConnectionString:Server=Localhost;Database=ChocolateyManagement;User ID=ChocoUser;Password=Ch0c0R0cks;'" -``` - -> :choco-warning: **WARNING** -> -> Please ensure the login has been given `db_datareader` and `db_datawriter` access to the database. See [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - ---- - -##### SQL Server Express - -```powershell -choco install chocolatey-management-web -y --package-parameters-sensitive="'/ConnectionString:Server=Localhost\SQLEXPRESS;Database=ChocolateyManagement;User ID=ChocoUser;Password=Ch0c0R0cks;'" -``` - -> :choco-warning: **WARNING** -> -> Please ensure the login has been given `db_datareader` and `db_datawriter` access to the database. See [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - -::: -:::{.tab-pane .fade #scenario-four role=tabpanel aria-labelledby=scenario-four-tab} - -#### SQL Server Authentication to Remote SQL Server - -Split - you are installing the management service(s) on a server, and targeting an existing SQL Server instance in your organization. You have set up the [database](xref:ccm-database) to use Mixed Mode Authentication. - -```powershell -choco install chocolatey-management-web -y --package-parameters-sensitive="'/ConnectionString:Server=;Database=ChocolateyManagement;User ID=ChocoUser;Password=Ch0c0R0cks;'" -``` - -> :choco-warning: **WARNING** -> -> Please ensure the login has been given `db_datareader` and `db_datawriter` access to the database. See [logins and access](xref:ccm-database#step-2-set-up-sql-server-logins-and-access). - -::: -:::: - -## Step 3: Verify Installation - -The `chocolatey-management-web` package is responsible for creating and deploying the Chocolatey Central Management Website within IIS. A successful installation of this package can be verified by: - -* Opening an internet browser on the machine to the following address `http://localhost` which should result in the login page for Chocolatey Central Management being displayed. -* It should be possible to login to the site using the default credentials mentioned in Step 4 (below). -* The installation folder for `chocolatey-management-web` is at `c:\tools\chocolatey-management-web` (this is configurable by `$env:ChocolateyToolsLocation`). -* Open the website log file located at `c:\tools\chocolatey-management-web\App_Data\Logs\ccm-website.log` and verify that there are no recently reported errors. If you are on a version of Chocolatey Central Management prior to 0.2.0, the log will be located at `c:\tools\chocolatey-management-web\App_Data\Logs\Logs.txt`. - -## Step 4: Set Up Website - -### Step 4.1: Login And Change Default Credentials - -When you access the Chocolatey Central Management Website you will be prompted to provide a username and password to access the site. By default, the username is `ccmadmin` and the password is `123qwe`. After you input this, you will be prompted to change the password. - -![First time login - change password](/assets/images/ccm-playwright/account/login/alert-additional-settings.png) - -### Step 4.2: SMTP Configuration - -In order to send email from Chocolatey Central Management, you will need to make sure that [all necessary settings have been configured](xref:ccm-administration-settings-email). - -#### `appsettings.json` configuration - -> :choco-info: **NOTE** -> -> In version 0.2.0+ of Chocolatey Central Management, this configuration will likely be automatically applied during installation and will use defaults but be encrypted. If the value is incorrect, you can simply set it as shown here as encryption is not necessary for this value. - -There is a requirement within the Chocolatey Central Management site to send emails to end users of the application when, for example, registering a new user or resetting a password. To ensure that these emails contain a properly clickable link a modification needs to be made to the `appsettings.json` file which is located in the `c:\tools\chocolatey-management-web` folder. - -Open this file in a text editor, and add the following entry: - -```json - "App": { - "WebSiteRootAddress": "" - } -``` - -> :choco-info: **NOTE** -> -> - `URL_to_CCM` should be the accessible URL to access the Chocolatey Central Management Website. -> This will typically be the FQDN of the server that is hosting the Chocolatey Central Management Website, but it will depend on your environment's configuration. -> - When adding this entry, be sure to include a `,` either before or after the entry, depending on where you add it in the file. -> In other words, the end result needs to be a properly formatted JSON document. - -The end result should look something like this: - -![Modified appsettings.json file](/assets/images/features/ccm/updated_appsettingsjson_file.png) - -Once this change has been added, save the file and then run the following to ensure that the process running the Chocolatey Central Management Website is stopped: - -```powershell -# For CCM versions older than v0.6.0 -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force - -# For CCM version 0.6.0 and 0.6.1 -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force -Stop-Website -Name ChocolateyCentralManagement -Restart-WebAppPool -Name ChocolateyCentralManagement -Start-Website -Name ChocolateyCentralManagement - -# For CCM v0.6.2 and up -Stop-Website -Name ChocolateyCentralManagement -Restart-WebAppPool -Name ChocolateyCentralManagement -Start-Website -Name ChocolateyCentralManagement -``` - -Then try accessing the website again. Any emails that are then sent from Chocolatey Central Management should then contain valid links back to the site. - -### Step 4.3: LDAP Configuration - -You may want to allow [authentication against LDAP](xref:ccm-administration-settings-user-management#ldap-configuration) for users that are logging into the Chocolatey Central Management website. - -### Step 4.4: Application Settings File - -Some application settings will require you to edit the `appsettings.json` file, which is located in the `c:\tools\chocolatey-management-web` folder. - -Here is a copy of items that can be set. They are not required to be encrypted. Any item that is encrypted can be replaced by a non-encrypted value. During package install/upgrade, Chocolatey will encrypt the settings (even if they were previously plain text). - -```json -{ - "ConnectionStrings": { - "Default": "Server=; Database=ChocolateyManagement; Trusted_Connection=True;" - }, - "App": { - "WebSiteRootAddress": "http://" - }, - "Recaptcha": { - "SiteKey": "", - "SecretKey": "" - } -} -``` - -> :choco-warning: **WARNING** -> -> Recaptcha is likely to require a publicly available Chocolatey Central Management Website, and we currently have a strong recommendation to **NOT** open up the website to the internet. You likely do not want to set this or turn it on inside the Administration -> Settings section. However, if you do, you will _need_ the items set here in the `appsettings.json` as well. - -### Step 4.5: Audit Retention - -You may want to configure the [automatic deletion of audit logs](xref:ccm-administration-settings-retention#audit-retention) that are captured by Chocolatey Central Management website. - -### Step 4.6: Stale Computer Retention - - -You may want to setup the [automatic deletion of computers](xref:ccm-administration-settings-retention#stale-computer-retention) that are no longer reporting into Chocolatey Central Management. - - -### Step 4.7: Set up Two Factor Login - -You may want to setup [two factor login](xref:ccm-administration-settings-security#two-factor-login) for users who are going to be logging into the Chocolatey Central Management website. - -## FAQ - -### What is the minimum required configuration for the `appsettings.json` file? - -As of Chocolatey Central Management v0.6.2, the default settings in the `appsettings.json` for the website package are: - -```json -{ - "ConnectionStrings": { - "Default": "Server=; Database=ChocolateyManagement; Trusted_Connection=True;" - }, - "App": { - "WebSiteRootAddress": "http://" - } -} -``` - -> :choco-info: **NOTE** -> -> This file will usually be condensed into a single line, with the values encrypted. - -If these values are removed or incorrect, the Chocolatey Central Management website may fail to start. -To correct this, ensure all configuration is present and correct and then restart the Chocolatey Central Management website. - -```powershell -Stop-Website -Name ChocolateyCentralManagement -Restart-WebAppPool -Name ChocolateyCentralManagement -Start-Website -Name ChocolateyCentralManagement -``` - -### Can I install the Chocolatey Central Management Website under a Virtual Directory in IIS? - -Currently, no. The Chocolatey Central Management Website expects to reside at the site level within IIS. - -### What is the Chocolatey Central Management Component Compatibility Matrix? - -Chocolatey Central Management has specific compatibility requirements with quite a few moving parts. It is important to understand that there are some Chocolatey Agent versions that may not be able to communicate with some versions of Chocolatey Central Management and vice versa. Please see the [Chocolatey Central Management Component Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix) for details. - -### I entered incorrect database details on install, do I need to reinstall to fix that? - -It depends. You can simply go to the `appsettings.json` file and adjust the connection string to be plaintext. It will remain in plaintext though (at least until upgrade), so if you have actual password details you need to keep secure, you should do a force installation. - -1. The file is located at `c:\tools\chocolatey-management-web\appsettings.json`. -1. You would open that up in an editor and modify the `"Default"` connection string. -1. It would look something like the following (adjust the connection string as necessary): - -```json -{ - "ConnectionStrings": { - "Default": "Server=; Database=ChocolateyManagement; Trusted_Connection=True;" - }, - "App": { - "WebSiteRootAddress": "http://" - } -} -``` - -1. Then restart the website by running from admin powershell: - - ```powershell - # For CCM versions older than v0.6.0 - Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force - - # For CCM version 0.6.0 and 0.6.1 - Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force - Stop-Website -Name ChocolateyCentralManagement - Restart-WebAppPool -Name ChocolateyCentralManagement - Start-Website -Name ChocolateyCentralManagement - - # For CCM v0.6.2 and up - Stop-Website -Name ChocolateyCentralManagement - Restart-WebAppPool -Name ChocolateyCentralManagement - Start-Website -Name ChocolateyCentralManagement - ``` - -> :choco-warning: **WARNING** -> -> Do not put `sec:` or `secure-` at the start (prefix) of any values that you are adding/modifying directly. That tells Chocolatey components they are encrypted and it will attempt to decrypt them for use. If that is done incorrectly, it will cause things to crash. - -### Where is the Chocolatey Central Management Website installed? - -The default installation folder for `chocolatey-management-web` is at `c:\tools\chocolatey-management-web`. However, this is configurable based on `$env:ChocolateyToolsLocation`. We would not suggest changing that value once you have installed anything that makes use of it as permissions and other things will be pointing to that set of folders. - -## Common Errors and Resolutions - -### Chocolatey Central Management Website fails to start, showing "An error occurred while starting the application." - -You may also see the following entry in the Chocolatey Central Management website log file: - -```log -System.ArgumentNullException: Value cannot be null. (Parameter 'str') -``` - -This indicates some of the [required configuration values][required-config] for the CCM website to function are not present. -Ensure all [required configuration values][required-config] are present, then restart the CCM website: - -```powershell -# For CCM versions older than v0.6.0 -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force - -# For CCM version 0.6.0 and 0.6.1 -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force -Stop-Website -Name ChocolateyCentralManagement -Restart-WebAppPool -Name ChocolateyCentralManagement -Start-Website -Name ChocolateyCentralManagement - -# For CCM v0.6.2 and up -Stop-Website -Name ChocolateyCentralManagement -Restart-WebAppPool -Name ChocolateyCentralManagement -Start-Website -Name ChocolateyCentralManagement -``` - -### Chocolatey Central Management Website fails to load with a `500.21` error code. - -This error code indicates that IIS failed to start the website due to a misconfiguration. -By default, Chocolatey Central Management uses the `AspNetCoreModuleV2` in IIS, however the initial versions of Chocolatey Central Management initially used `AspNetCoreModule` instead. -Due to how the upgrade logic has worked prior to v0.6.2, this old configuration value may be kept during upgrade. - -As of v0.6.0, the IIS webhost can no longer run the website using the `AspNetCoreModule` as 0.6.x is running on .NET Core 3.1, and the structure of the `web.config` file has changed. -If you encounter this issue, you will need to update your `web.config` file to match the new format. -The default `web.config` file structure as of v0.6.0 is as follows: - -```xml - - - - - - - - - - - -``` - -As of v0.6.2, the `chocolatey-management-website` package upgrade process will inform you during upgrade if your `web.config` file is not usable. -If it is not, the installer will show a large warning message, indicating where the existing `web.config` file has been backed up to. -After the installation completes, you will need to replicate any customizations you have made to the `web.config` file into the new file manually. - -### Configure Chocolatey Central Management alongside WSUS admin site. - - - -### The specified path, file name, or both are too long. - -This error can occur when installing the `chocolatey-management-web` package. Due to the nested folder structure contained within this package, when extracting to the default cache location, the path can become too long. This problem is known is occur in the 0.1.0-beta-20181009 release of this package, and it should be corrected in subsequent releases. As a workaround, adding the following parameters to the install command should allow the installation to complete successfully: - -```powershell ---cache-location="'C:\Temp\choco'" -``` - -### HTTP Error when trying to access Chocolatey Central Management Website. - -When you try to access the Chocolatey Central Management Website (by default, this is hosted on `http://localhost`), errors messages similar to the following may be returned: - -`HTTP Error 500.19 - Internal Server Error` - -These errors happen very early in the application execution, and as a result, are not logged to the standard log location. It is possible to increase the logging that is performed by the ASP.NET Worker Process, so that additional information about the error can be found. Follow these steps to enable that additional logging: - -1. In Windows Explorer, navigate to the `c:/tools/chocolatey-management-web` folder -1. Find the `web.config` file and open this in a text editor -1. Locate the `stdoutLogEnabled` attribute, which will be set to false by default -1. Change this to true, and save the file -1. Check to see if there is a running process called `ChocolateySoftware.ChocolateyManagement.Web.Mvc.exe`. If there is, stop it. -1. Restart the CCM app pool and website in IIS. -1. Attempt to access the website again. An additional log file will be created in the `App_Data\Logs\stdout` folder. In Chocolatey Central Management v0.6.0 and v0.6.1, this may be incorrectly located in the `Logs\stdout` folder. -1. Review this log for additional error information -1. Ensure that you set the `stdoutLogEnabled` attribute back to false - -In these situations, we have found that incorrect database connection strings are typically the root cause of the problem. - -Another possible cause for this error is if there are mismatching versions of `dotnet-6.0-aspnetruntime` and `dotnet-aspnetcoremodule-v2`. Ensure that both are on the same patch level. Note that `dotnet-aspnetcoremodule-v2` package versioning does not directly correspond to the dotnet patch level, so it is recommended to use the versions specified in the prerequisites above - -### The term 'Install-ChocolateyAppSettingsJsonFile' is not recognized as the name of a cmdlet, function, script file, or operable program. - -In the beta version of Chocolatey Licensed Extension, there was a cmdlet named `Install-ChocolateyAppSettingsJsonFile` and this was used in the 0.1.0-beta-20181009 release of the Chocolatey Central Management components. In the final released version of the Chocolatey Licensed Extension, this was renamed to `Install-AppSettingsJsonFile`. - -As a result, the Chocolatey Central Management beta no longer works with the released version of Chocolatey Licensed Extension. This will be corrected once the next release of the Chocolatey Central Management components is completed. - -### Cannot process command because of one or more missing mandatory parameters: FilePath. - -During the creation of Chocolatey Central Management, some additional PowerShell cmdlets were created, and these are installed as part of the Chocolatey Licensed Extension package. These cmdlets went through a number of iterations, and as a result, different combinations of Chocolatey Central Management packages were incompatible with the Chocolatey Licensed Extension package, resulting in the error: - -`Cannot process command because of one or more missing mandatory parameters: FilePath` - -The guidance in this case is either to pin to the specific version of the Chocolatey Extension package required by the version of Chocolatey Central Management being used, or, update to the latest versions of all packages, where the situation should be addressed. - -### All attempts to send email from Chocolatey Central Management result in an error. - -When any attempt is made by Chocolatey Central Management to send an email, an error occurs. This either results in an HTTP 500 errors similar to the following: - -![HTTP 500 error when sending email](/assets/images/features/ccm/error_when_sending_email_500.png) - -Or an inline error, with text similar to: "Unable to send email, please contact System Administrator to ensure SMTP settings are configured correctly.". - -Checking the log file, an error similar to this is found: - -```powershell -ERROR 2019-06-14 00:54:03,491 [55 ] Microsoft.AspNetCore.Server.Kestrel - Connection id "0HLNGIPBBV01R", Request id "0HLNGIPBBV01R:00000001": An unhandled exception was thrown by the application. -System.Net.Sockets.SocketException (0x80004005): No connection could be made because the target machine actively refused it 127.0.0.1:25 -``` - -This is caused due to the default SMTP configuration being used by CCM, which is incompatible with the environment. Chocolatey Central Management, by default, assumes that there is an available SMTP Server available on the current machine, using port 25. To fix this, follow the [configuration steps](xref:ccm-administration-settings-email). - -### Emails sent from Chocolatey Central Management to users have links that contain localhost, rather than the actual Chocolatey Central Management Server name. - -There is a requirement within the Chocolatey Central Management site to send emails to end users of the application when, for example, registering a new user or resetting a password. When this happens, the email should contain a link back to the Chocolatey Central Management site, which the user can click on to bring up the site in their browser. However, emails sent from Chocolatey Central Management contain links that contain localhost in the address, which means when clicked on, they fail to open correctly. This can be fixed by making a change to the `appsettings.json` file which is located in the `c:\tools\chocolatey-management-web` folder. - -Open this file in a text editor, and add the following entry: - -```json - "App": { - "WebSiteRootAddress": "" - } -``` - -> :choco-info: **NOTE** -> -> When adding this entry, be sure to include a `,` either before or after the entry, depending on where you add it in the file. i.e. the end result needs to be a properly formatted JSON document. - -where `URL_to_CCM` should be the accessible URL to access the Chocolatey Central Management Website. This will typically be the FQDN of the server that is hosting the Chocolatey Central Management Website, but it will depend on your environment's configuration. - -The end result should look something like this: - -![Modified appsettings.json file](/assets/images/features/ccm/updated_appsettingsjson_file.png) - -Once this change has been added, save the file, and then run the following to ensure that the process running the Chocolatey Central Management Website is stopped: - -```powershell -# For CCM versions older than v0.6.0 -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force - -# For CCM version 0.6.0 and 0.6.1 -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force -Stop-Website -Name ChocolateyCentralManagement -Restart-WebAppPool -Name ChocolateyCentralManagement -Start-Website -Name ChocolateyCentralManagement - -# For CCM v0.6.2 and up -Stop-Website -Name ChocolateyCentralManagement -Restart-WebAppPool -Name ChocolateyCentralManagement -Start-Website -Name ChocolateyCentralManagement -``` - -And then try accessing the website again. Any emails that are then sent from Chocolatey Central Management should then contain valid links back to the site. - -### The updated license file is not being picked up in the website. - -You need to restart the web executable currently. We are looking to have it automatically picked up in future releases. Here's a script to handle that: - -```powershell -# For CCM versions older than v0.6.0 -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force - -# For CCM version 0.6.0 and 0.6.1 -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force -Stop-Website -Name ChocolateyCentralManagement -Restart-WebAppPool -Name ChocolateyCentralManagement -Start-Website -Name ChocolateyCentralManagement - -# For CCM v0.6.2 and up -Stop-Website -Name ChocolateyCentralManagement -Restart-WebAppPool -Name ChocolateyCentralManagement -Start-Website -Name ChocolateyCentralManagement - -# Restart Chocolatey Agent and/or CCM service (all versions) -Get-Service chocolatey-* | Restart-Service -``` - -### A computer or group is not showing as available for deployments but I have plenty of available licenses. - -Once you upgrade to Chocolatey Central Management v0.3.0+, you have upgraded the Agent on the machine to v0.11.0+, and it has successfully completed a check in, then that messaging should go away. Note that clients do not get a message back that there was a failure as a security feature - you'll need to consult the Chocolatey Central Management Service logs. You can find that at `$env:ChocolateyInstall\logs\ccm-service.log`, or if you are on a version of Chocolatey Central Management prior to 0.2.0, the log will be located at `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\logs\chocolatey.service.host.log`. - -### Failed to generate a user instance of SQL Server due to failure in retrieving the user's local application data path. - -You may see the following: "System.Data.SqlClient.SqlException (0x80131904): Failed to generate a user instance of SQL Server due to failure in retrieving the user's local application data path. Please make sure the user has a local user profile on the computer. The connection will be closed." - -This means you are attempting to attach a Local DB file as part of your connection. This is an invalid scenario. - -### The website app pool shuts down almost as soon as it is started. - -If you see the app pool shutting down immediately when you start it. - -* Check the event log first. It's very helpful in seeing what the actual issues are -* Turn on stdout logging in the config at `c:\tools\chocolatey-management-web\web.config` if it is not already on. The attribute is named `stdoutLogEnabled` (set it to true). This will allow logging to `c:\tools\chocolatey-management-web\App_Data\Logs`. Permissions will play a role in this so ensure [the user has the right access](#non-default-app-pool-user-considerations). -* Check for [Non-Default App Pool User Considerations](#non-default-app-pool-user-considerations). - -### Errors when attempting to communicate with SignalR. - -Within the Chocolatey Central Management Website, [SignalR](https://dotnet.microsoft.com/apps/aspnet/signalr) is used to enable real time communications for notifications. It has been found that the following errors can be shown within the Developer Tools sections of some browsers: - -* Error: Connection disconnected with error 'Error: Cannot send until the transport is connected' -* The connection to ... was interrupted while the page was loading. Error: Connection disconnected with error 'Error: Error occurred' -* Error: failed to start the connection: Error: Unable to connect to the server with any of the available transports. ServerSentEvents failed: Error: 'ServerSentEvents' is disabled by the client. LongPolling failed: Error: 'LongPolling' is disabled by the client. - -In all of these cases, we haven't seen any drop in functionality for the notifications that are sent from the Chocolatey Central Management application. Our suspicion is that there is a timing issue when attempting to make the connection to the SignalR Hub, which is almost immediately rectified. Due to the fact that SignalR is a 3rd party integration, we do not believe that there is anything that can be done to resolve this problem, and since the functionality continues to work as expected, these errors in the JavaScript console can safely be ignored. - -[Central Management Setup](xref:ccm-setup) | [Chocolatey Central Management](xref:central-management) - -[required-config]: #what-is-the-minimum-required-configuration-for-the-appsettingsjson-file - -### Current user did not login to the application! - -After upgrading to v0.6.0/0.6.1/0.6.2 of the Chocolatey Central Management Website, you may see the error message: - -> Current user did not login to the application! - -When you attempt to login to the application, and you will be immediately logged out again. - -Full details of this problem can be found in the [GitHub issue](https://github.com/chocolatey/chocolatey-licensed-issues/issues/260), including a workaround for the problem. - -This issue has been addressed in v0.6.3. diff --git a/input/en-us/central-management/usage/api/examples.md b/input/en-us/central-management/usage/api/examples.md deleted file mode 100644 index 54742fcce3..0000000000 --- a/input/en-us/central-management/usage/api/examples.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -Order: 10 -xref: ccm-api-examples -Title: Examples -Description: CCM API usage examples ---- - -## Creating An _All Computers_ Group and Deploy Application Upgrades - -From a completely fresh CCM instance with at least one computer checking into Central Management, this process will: - -- Create a new group containing all the computers currently registered to Central Management. -- Create a new Deployment Plan with a single step, which will upgrade all Chocolatey-managed applications to the latest available versions. -- Start the Deployment Plan. - -The process involves a couple of intermediary steps as well, since we're using the raw REST API endpoints here (see below). -We're also assuming as part of this example that you've already [Authenticated to the CCM API](#authentication) and have a `$Session` variable created as in that example. - -### 1. Get All CCM-Managed Computers - -```powershell -$CcmServerHostname = 'chocoserver' -$params = @{ - Uri = "https://$CCmServerHostname/api/services/app/Computers/GetAll" - Method = 'GET' - WebSession = $Session -} -$ComputerList = Invoke-RestMethod @params -``` - -### 2. Create an _All Computers_ Group - -```powershell -# Create group in CCM -$GroupName = 'All Clients' -$Params = @{ - Uri = "https://$CcmServerHostname/api/services/app/Groups/CreateOrEdit" - Method = 'POST' - WebSession = $Session - ContentType = 'application/json' - Body = @{ - name = $GroupName - description = 'All CCM client machines' - groups = @() - computers = @( - $ComputerList.result | Select-Object -Property @{ Name = 'computerId'; Expression = { "$($_.id)" } } - ) - } | ConvertTo-Json -} -$null = Invoke-RestMethod @params - -# Retrieve created group information -$params = @{ - Uri = "https://$CcmServerHostname/api/services/app/Groups/GetAll" - Method = "GET" - WebSession = $Session -} -$Group = Invoke-RestMethod @params | - Select-Object -ExpandProperty result | - Where-Object Name -EQ $GroupName -``` - -### 3. Create a New Deployment Plan - -```powershell -$params = @{ - Uri = "https://$CcmServerHostname/api/services/app/DeploymentPlans/CreateOrEdit" - Method = "POST" - WebSession = $Session - ContentType = 'application/json' - Body = @{ name = "Upgrade Chocolatey-Managed Applications [$(Get-Date)]" } | ConvertTo-Json -} -$deployment = (Invoke-RestMethod @params).result -``` - -### 4. Add a Deployment Step - -```powershell -$params = @{ - Uri = "https://$CcmServerHostname/api/services/app/DeploymentSteps/CreateOrEdit" - Method = "POST" - WebSession = $Session - ContentType = 'application/json' - Body = @{ - deploymentPlanId = $deployment.Id - name = "Choco Upgrade All" - validExitCodes = "0, 1605, 1614, 1641, 3010" - executionTimeoutInSeconds = 14400 - machineContactTimeoutInMinutes = "0" - failOnError = $true - requireSuccessOnAllComputers = $false - deploymentStepGroups = @( - @{ groupId = $Group.Id; groupName = $Group.Name } - ) - # Syntax for basic Deployment Steps is "|" - script = "upgrade|all" - } | ConvertTo-Json -} -$null = Invoke-RestMethod @params -``` - -### 5. Move Deployment Plan to Ready & Start the Deployment Plan - -```powershell -$params = @{ - Uri = "https://$CcmServerHostname/api/services/app/DeploymentPlans/MoveToReady" - Method = "POST" - WebSession = $Session - ContentType = 'application/json' - Body = @{ id = $deployment.Id } | ConvertTo-Json -} -$null = Invoke-RestMethod @params - -$params = @{ - Uri = "https://$CcmServerHostname/api/services/app/DeploymentPlans/Start" - Method = "POST" - WebSession = $Session - ContentType = 'application/json' - Body = @{ id = $deployment.Id } | ConvertTo-Json -} -$null = Invoke-RestMethod @params -``` - -## Create a Recurring Scheduled Task to run Recurring Deployment Plans - -This example uses the concepts in the previous example and streamlines the process of creating a scheduled task on Windows to create a recurring Deployment Plan task. -In this example, we set the trigger to run daily, but you could configure it to run as needed for your use case. - -```powershell -$recurringDeploymentScript = { - # Fill in the CCM Server name as well as the Group ID that the Deployment Step will target - $CcmServerHostname = 'chocoserver' - $GroupId = 1 - - # Authenticate to API - # NOTE: This is an example only; it's never a great idea to store your credentials in a script or scheduled task. - # Instead, store the credentials securely and retrieve them during the scheduled task script. - $body = @{ - usernameOrEmailAddress = 'ccmadmin' - password = 'ch0c0R0cks' - } - - $null = Invoke-WebRequest -Uri "https://$CcmServerHostname/Account/Login" -Method POST -ContentType 'application/x-www-form-urlencoded' -Body $body -SessionVariable Session -ErrorAction Stop - - # Create New Deployment Plan - $params = @{ - Uri = "https://$CcmServerHostname/api/services/app/DeploymentPlans/CreateOrEdit" - Method = "POST" - WebSession = $Session - ContentType = 'application/json' - Body = @{ name = "Upgrade Chocolatey-Managed Applications [$(Get-Date)]" } | ConvertTo-Json - } - $deployment = (Invoke-RestMethod @params).result - - # Add Deployment Step - $params = @{ - Uri = "https://$CcmServerHostname/api/services/app/DeploymentSteps/CreateOrEdit" - Method = "POST" - WebSession = $Session - ContentType = 'application/json' - Body = @{ - deploymentPlanId = $deployment.Id - name = "Choco Upgrade All" - validExitCodes = "0, 1605, 1614, 1641, 3010" - executionTimeoutInSeconds = 14400 - machineContactTimeoutInMinutes = "0" - failOnError = $true - requireSuccessOnAllComputers = $false - deploymentStepGroups = @( - @{ groupId = $GroupId } - ) - script = "upgrade|all" - } | ConvertTo-Json - } - $null = Invoke-RestMethod @params - - # Move Deployment Plan to Ready & Start the Deployment Plan - $params = @{ - Uri = "https://$CcmServerHostname/api/services/app/DeploymentPlans/MoveToReady" - Method = "POST" - WebSession = $Session - ContentType = 'application/json' - Body = @{ id = $deployment.Id } | ConvertTo-Json - } - $null = Invoke-RestMethod @params - - $params = @{ - Uri = "https://$CcmServerHostname/api/services/app/DeploymentPlans/Start" - Method = "POST" - WebSession = $Session - ContentType = 'application/json' - Body = @{ id = $deployment.Id } | ConvertTo-Json - } - $null = Invoke-RestMethod @params -} - -$argumentString = '-NoProfile -WindowStyle Hidden -Command "& {{ {0} }}"' -f $recurringDeploymentScript - -$taskParams = @{ - Action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument $argumentString - # Fill in the requirements for the repeating scheduled task; here, it will trigger once a day @ 6 PM - Trigger = New-ScheduledTaskTrigger -Daily -At 6pm - TaskName = 'Repeat - Choco Update Deployment' - Description = "Create and start a Chocolatey Central Management Deployment Plan which will trigger all computers in the group '$groupName' to update their Chocolatey-managed applications." -} - -Register-ScheduledTask @taskParams -``` diff --git a/input/en-us/central-management/usage/api/index.md b/input/en-us/central-management/usage/api/index.md deleted file mode 100644 index 6736fd80c1..0000000000 --- a/input/en-us/central-management/usage/api/index.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -Order: 30 -xref: ccm-api -Title: API -Description: Information on using the CCM API -RedirectFrom: docs/central-management-api ---- - -## Description - -As of CCM v0.4.0, the API for Chocolatey Central Management is exposed via Swagger. -The API documentation and examples can be reached from your CCM dashboard by selecting the :gear: **API** option on the left sidebar. -The information contained there is referenced here, but you can additionally try out the various API endpoints directly from the Swagger API page for your own CCM environment. - -> :choco-warning: **WARNING** -> -> The Swagger UI does not work in Internet Explorer. Please use another browser. - -## ChocoCCM - -The [ChocoCCM](xref:chococcm) PowerShell module is available from the PowerShell Gallery for use with CCM v0.4.0 and later. -This module contains PowerShell commands designed for interfacing with the CCM API directly. - -See the [ChocoCCM Function Reference](xref:chococcm-functions) page for a full list of commands and their associated documentation. - -## Authentication - -Before being able to utilise the CCM API, you will need to create an authenticated session. -This can be done by targeting the `/Account/Login` endpoint and submitting the username and password. -You will need to use the authenticated session variable for any API calls. - -```powershell -# Replace 'chocoserver' with the hostname of your CCM server in your environment -$CcmServerHostname = 'chocoserver' -$Credential = Get-Credential -$body = @{ - usernameOrEmailAddress = $Credential.UserName - password = $Credential.GetNetworkCredential().Password -} -$Result = Invoke-WebRequest -Uri "https://$CcmServerHostname/Account/Login" -Method POST -ContentType 'application/x-www-form-urlencoded' -Body $body -SessionVariable Session -ErrorAction Stop -``` - -While authenticated, you can target API endpoints like this: - -```powershell -# The $Session variable name must match the string given to -SessionVariable when authenticating. -Invoke-WebRequest -Uri "https://$CcmServerHostname/$endpointUrl" -Method $Method -Body $Parameters -Session $Session -``` - -## Endpoints - -Below is a list of the API endpoints available for CCM as of v0.10.0. -For more detailed information on the API endpoints and their parameters for your version of CCM, select the :gear: **API** option from the sidebar on the Central Management dashboard, or navigate to `https://CCM_SERVER_HOSTNAME/swagger/`. - -### AuditLog - -| Method | EndpointUrl | -| :----: | :-------------------------------------- | -| GET | /api/services/app/AuditLog/GetAuditLogs | - -### ChocolateyLicenseInformation - -| Method | EndpointUrl | -| :----: | :-------------------------------------------------------------------- | -| GET | /api/services/app/ChocolateyLicenseInformation/GetLicenseCount | -| GET | /api/services/app/ChocolateyLicenseInformation/GetLicenseExpiration | -| GET | /api/services/app/ChocolateyLicenseInformation/GetIsTrialLicense | -| GET | /api/services/app/ChocolateyLicenseInformation/GetIsLicenseCountValid | - -### ComputerGroup - -| Method | EndpointUrl | -| :----: | :------------------------------------------------- | -| GET | /api/services/app/ComputerGroup/GetAllByComputerId | -| GET | /api/services/app/ComputerGroup/GetAllByGroupId | -| POST | /api/services/app/ComputerGroup/CreateOrEdit | -| DELETE | /api/services/app/ComputerGroup/Delete | - -### Computers - -| Method | EndpointUrl | -| :----: | :----------------------------------------------------------- | -| GET | /api/services/app/Computers/GetComputerCount | -| GET | /api/services/app/Computers/GetAllPaged | -| GET | /api/services/app/Computers/GetAll | -| GET | /api/services/app/Computers/GetComputerForView | -| GET | /api/services/app/Computers/GetComputerForEditByComputerGuid | -| GET | /api/services/app/Computers/GetComputerForEdit | -| POST | /api/services/app/Computers/Edit | -| DELETE | /api/services/app/Computers/Delete | - -### ComputerSoftware - -Methods for querying or managing mappings between Computer objects and Software entries - -| Method | EndpointUrl | -| :----: | :--------------------------------------------------------- | -| GET | /api/services/app/ComputerSoftware/GetAllByComputerId | -| GET | /api/services/app/ComputerSoftware/GetAllPagedByComputerId | -| GET | /api/services/app/ComputerSoftware/GetAllBySoftwareId | -| GET | /api/services/app/ComputerSoftware/GetAllPagedBySoftwareId | - -### DeploymentPlans - -| Method | EndpointUrl | -| :----: | :--------------------------------------------------------------------------- | -| GET | /api/services/app/DeploymentPlans/GetAllPaged | -| GET | /api/services/app/DeploymentPlans/GetAll | -| GET | /api/services/app/DeploymentPlans/GetDeploymentPlanForView | -| GET | /api/services/app/DeploymentPlans/GetAllScheduledDeploymentPlansReadyToStart | -| GET | /api/services/app/DeploymentPlans/GetDeploymentPlanForEdit | -| POST | /api/services/app/DeploymentPlans/CreateOrEdit | -| DELETE | /api/services/app/DeploymentPlans/Delete | -| DELETE | /api/services/app/DeploymentPLans/DeleteNewDraftDeploymentPlan | -| POST | /api/services/app/DeploymentPlans/Archive | -| POST | /api/services/app/DeploymentPlans/Duplicate | -| POST | /api/services/app/DeploymentPlans/Start | -| POST | /api/services/app/DeploymentPlans/Cancel | -| POST | /api/services/app/DeploymentPlans/MoveToReady | - -### DeploymentStepComputers - -| Method | EndpointUrl | -| :----: | :------------------------------------------------------------------------------------ | -| GET | /api/services/app/DeploymentStepComputers/GetAllPagedByDeploymentStepId | -| GET | /api/services/app/DeploymentStepComputers/GetAllByDeploymentStepId | -| GET | /api/services/app/DeploymentStepComputers/GetDeploymentStepComputerForView | -| GET | /api/services/app/DeploymentStepComputers/GetDeploymentStepComputerForEdit | -| GET | /api/services/app/DeploymentStepComputers/GetReadyDeploymentStepComputerByMachineGuid | -| GET | /api/services/app/DeploymentStepComputers/GetUnreachableDeploymentStepComputers | -| GET | /api/services/app/DeploymentStepComputers/GetStaleActiveDeploymentStepComputers | -| POST | /api/services/app/DeploymentStepComputers/CreateOrEdit | -| DELETE | /api/services/app/DeploymentStepComputers/Delete | -| GET | /api/services/app/DeploymentStepComputers/GetDeploymentStepDetailsToZip | - -### DeploymentStepGroups - -| Method | EndpointUrl | -| :----: | :------------------------------------------------------------------- | -| GET | /api/services/app/DeploymentStepGroups/GetDeploymentStepGroupForView | -| GET | /api/services/app/DeploymentStepGroups/GetDeploymentStepGroupForEdit | -| POST | /api/services/app/DeploymentStepGroups/CreateOrEdit | -| DELETE | /api/services/app/DeploymentStepGroups/Delete | - -### DeploymentSteps - -| Method | EndpointUrl | -| :----: | :-------------------------------------------------------------- | -| GET | /api/services/app/DeploymentSteps/GetAllPagedByDeploymentPlanId | -| GET | /api/services/app/DeploymentSteps/GetAllByDeploymentPlanId | -| GET | /api/services/app/DeploymentSteps/GetDeploymentStepForView | -| GET | /api/services/app/DeploymentSteps/GetDeploymentStepForEdit | -| POST | /api/services/app/DeploymentSteps/CreateOrEdit | -| POST | /api/services/app/DeploymentSteps/CreateOrEditPrivileged | -| DELETE | /api/services/app/DeploymentSteps/Delete | -| DELETE | /api/services/app/DeploymentSteps/DeletePrivileged | - -### Groups - -| Method | EndpointUrl | -| :----: | :--------------------------------------- | -| GET | /api/services/app/Groups/GetAllPaged | -| GET | /api/services/app/Groups/GetAll | -| GET | /api/services/app/Groups/GetGroupForEdit | -| POST | /api/services/app/Groups/CreateOrEdit | -| DELETE | /api/services/app/Groups/Delete | - -### OutdatedReports - -| Method | EndpointUrl | -| :----: | :------------------------------------------------- | -| GET | /api/services/app/OutdatedReports/GetAllPaged | -| GET | /api/services/app/OutdatedReports/GetAll | -| GET | /api/services/app/OutdatedReports/GetAllByReportId | -| POST | /api/services/app/OutdatedReports/Create | -| DELETE | /api/services/app/OutdatedReports/Delete | - -### Permission - -| Method | EndpointUrl | -| :----: | :--------------------------------------------- | -| GET | /api/services/app/Permission/GetAllPermissions | - -### Role - -| Method | EndpointUrl | -| :----: | :---------------------------------------- | -| GET | /api/services/app/Role/GetRoles | -| GET | /api/services/app/Role/GetRoleForEdit | -| POST | /api/services/app/Role/CreateOrUpdateRole | -| DELETE | /api/services/app/Role/DeleteRole | - -### SensitiveVariables - -| Method | EndpointUrl | -| :----: | :--------------------------------------------------------------- | -| GET | /api/services/app/SensitiveVariables/GetAllPaged | -| GET | /api/services/app/SensitiveVariables/GetAll | -| GET | /api/services/app/SensitiveVariables/GetSensitiveVariableForView | -| POST | /api/services/app/SensitiveVariables/Create | -| DELETE | /api/services/app/SensitiveVariables/Delete | - -### Software - -| Method | EndpointUrl | -| :----: | :----------------------------------------------------------------- | -| GET | /api/services/app/Software/GetAll | -| GET | /api/services/app/Software/GetAllCurrentlyInstalled | -| GET | /api/services/app/Software/GetAllWithoutFilter | -| GET | /api/services/app/Software/GetSoftwareByPackageId | -| GET | /api/services/app/Software/GetSoftwareByPackageIdAndVersion | -| GET | /api/services/app/Software/GetSoftwareForView | -| GET | /api/services/app/Software/GetSoftwareForEdit | -| GET | /api/services/app/Software/GetSoftwareForEditByPackageIdAndVersion | - -### TokenAuth - -| Method | EndpointUrl | -| :----: | :------------------------------------------------ | -| POST | /api/TokenAuth/Authenticate | -| POST | /api/TokenAuth/RefreshToken | -| GET | /api/TokenAuth/LogOut | -| POST | /api/TokenAuth/SendTwoFactorAuthCode | -| POST | /api/TokenAuth/ImpersonatedAuthenticate | -| POST | /api/TokenAuth/LinkedAccountAuthenticate | -| GET | /api/TokenAuth/GetExternalAuthenticationProviders | -| POST | /api/TokenAuth/ExternalAuthenticate | -| GET | /api/TokenAuth/TestNotification | - -### WebLog - -| Method | EndpointUrl | -| :----: | :---------------------------------------- | -| GET | /api/services/app/WebLog/GetLatestWebLogs | -| POST | /api/services/app/WebLog/DownloadWebLogs | diff --git a/input/en-us/central-management/usage/examples/deployment-plans.md b/input/en-us/central-management/usage/examples/deployment-plans.md deleted file mode 100644 index 889f1e1156..0000000000 --- a/input/en-us/central-management/usage/examples/deployment-plans.md +++ /dev/null @@ -1,372 +0,0 @@ ---- -Order: 10 -xref: ccm-example-deployment-plans -Title: Deployment Plans -Description: Example Deployment Plans that can be imported into Chocolatey Central Management for immediate use. -RedirectFrom: en-us/central-management/usage/examples/deployments ---- - -## Summary - -Chocolatey Central Management (CCM) now (in version 0.11.0 and up) supports importing and exporting Deployment Plans. We have several example Deployment Plans that you can import and use immediately, to help you make best use of your Chocolatey for Business suite! - - - -### Updating Values in Deployment Plans - -When importing an example Deployment Plan, you may have to update the `Target Group(s)` and any `Deployment Start Time` that are set. - -After importing the Deployment Plan, you should follow these steps to ensure you are able to deploy it! - -#### Setting the Target Group(s) - -You will also need to set a Target Group for the Deployment Step: - -- Mouse-over the Deployment Step and click the **Edit** button. - ![Editing a Deployment Step](/assets/images/ccm-playwright/deployment-plans/edit/button-edit-step.png) - -- Navigate to the `Select Target Groups` panel. - -- Highlight your preferred groups and click the **>** button to move them into `Selected Groups`. - ![Selecting Target Groups](/assets/images/ccm-playwright/deployment-plans/edit/modal-step-select-target-groups.png) - -- Click **Save**. - -#### Setting the Start Time Date (Scheduled Deployments) - -Before you can run the Deployment Plan, you must set the `Start Date Time` to a time at least 30 minutes in the future. - -To do so, click on the clock icon next to the `Start Date Time` field. When you have selected an appropriate time, click **Save**. - -![Updating an invalid Start Date Time](/assets/images/ccm-playwright/deployment-plans/edit/calendar-start-date-time.png) - -## Example Deployment Plans - -We have several example Deployment Plans shown below, and you can check the [Chocolatey Central Management Deployment Plan Examples repository](https://github.com/chocolatey/ccm-deployment-examples) on GitHub for more. - -#### Installing or Upgrading a Package - -The only Deployment Step in this Deployment Plan upgrades, or installs if not present, the `Firefox` package ([available on the Chocolatey Community Repository](https://community.chocolatey.org/packages/firefox)). - -Assuming this package was available on your sources, you will only need to set the Target Groups for the Deployment Step. If you don't have it available, you can download it using `choco download firefox --source="'https://community.chocolatey.org/api/v2/'"` and then upload it to your internal repository. - -Save the following as a `.json` file to import as a Chocolatey Central Management Deployment Plan: - - - -
- -```json -{ - "Name": "Installing a Package (Simple)", - "ScheduledDateTimeUtc": null, - "LastScheduledDateTimeUtc": null, - "RepeatPeriod": 0, - "ExecutionTimeoutInSeconds": 14400, - "RequiresApproval": false, - "DeploymentSteps": [ - { - "Name": "Deploy Firefox", - "IsPrivileged": false, - "PlanOrder": 1, - "Script": "upgrade|firefox||false", - "ValidExitCodes": "0, 1605, 1614, 1641, 3010", - "ExecutionTimeoutInSeconds": 14400, - "FailOnError": true, - "RequireSuccessOnAllComputers": false, - "MachineContactTimeoutInMinutes": 0, - "DeploymentStepGroupIds": [] - } - ] -} -``` -
- -#### Installing Multiple Packages - -This Deployment Plan is a basic example of deploying multiple packages. - -We recommend that you use a separate Deployment Step for each package to deploy to allow per-computer reporting. - -You can use this to generate larger Deployment Plans with more comprehensive suites of packages, even mixing Basic and Advanced Deployment Steps in order to provide additional configuration. - -Save the following as a `.json` file to import as a Chocolatey Central Management Deployment Plan: - - - -
- -```json -{ - "Name": "Deploying Multiple Packages", - "ScheduledDateTimeUtc": null, - "LastScheduledDateTimeUtc": null, - "RepeatPeriod": 0, - "ExecutionTimeoutInSeconds": 14400, - "RequiresApproval": false, - "DeploymentSteps": [ - { - "Name": "Deploy Cloudflared", - "IsPrivileged": false, - "PlanOrder": 1, - "Script": "upgrade|cloudflared||false", - "ValidExitCodes": "0, 1605, 1614, 1641, 3010", - "ExecutionTimeoutInSeconds": 14400, - "FailOnError": true, - "RequireSuccessOnAllComputers": false, - "MachineContactTimeoutInMinutes": 0, - "DeploymentStepGroupIds": [] - }, - { - "Name": "Deploy Firefox", - "IsPrivileged": false, - "PlanOrder": 2, - "Script": "upgrade|firefox||false", - "ValidExitCodes": "0, 1605, 1614, 1641, 3010", - "ExecutionTimeoutInSeconds": 14400, - "FailOnError": true, - "RequireSuccessOnAllComputers": false, - "MachineContactTimeoutInMinutes": 0, - "DeploymentStepGroupIds": [] - }, - { - "Name": "Deploy VSCode", - "IsPrivileged": false, - "PlanOrder": 3, - "Script": "upgrade|vscode||false", - "ValidExitCodes": "0, 1605, 1614, 1641, 3010", - "ExecutionTimeoutInSeconds": 14400, - "FailOnError": true, - "RequireSuccessOnAllComputers": false, - "MachineContactTimeoutInMinutes": 0, - "DeploymentStepGroupIds": [] - }, - { - "Name": "Deploy 7zip", - "IsPrivileged": false, - "PlanOrder": 4, - "Script": "upgrade|7zip||false", - "ValidExitCodes": "0, 1605, 1614, 1641, 3010", - "ExecutionTimeoutInSeconds": 14400, - "FailOnError": true, - "RequireSuccessOnAllComputers": false, - "MachineContactTimeoutInMinutes": 0, - "DeploymentStepGroupIds": [] - } - ] -} -``` -
- -#### Installing a Package with Parameters - -This Deployment Plan is an example of deploying a package using an Advanced Deployment Step, in this case to provide a package parameter during deployment. - -The example passes the `/InstallDir` parameter to the `python312` package, causing the package to be installed to the location provided. - -We use the Advanced Deployment Step to do this because the Basic Deployment Step does not allow package parameters to be used. - -Save the following as a `.json` file to import as a Chocolatey Central Management Deployment Plan: - - - -
- -```json -{ - "Name": "Deployment Plan with Parameters", - "ScheduledDateTimeUtc": null, - "LastScheduledDateTimeUtc": null, - "RepeatPeriod": 0, - "ExecutionTimeoutInSeconds": 14400, - "RequiresApproval": false, - "DeploymentSteps": [ - { - "Name": "Deploy Python to Agent Directory", - "IsPrivileged": true, - "PlanOrder": 1, - "Script": "choco install python312 --package-parameters=\"'/InstallDir:C:\\BuildAgent\\tools\\python312'\"\nexit $LASTEXITCODE", - "ValidExitCodes": "0, 1605, 1614, 1641, 3010", - "ExecutionTimeoutInSeconds": 14400, - "FailOnError": true, - "RequireSuccessOnAllComputers": false, - "MachineContactTimeoutInMinutes": 0, - "DeploymentStepGroupIds": [] - } - ] -} -``` -
- -### Advanced Deployments - -#### Using a Deployment Schedule - -The following Deployment Plan maintains your Chocolatey license in your environment. It assumes that as a Chocolatey for Business customer -you have created a `chocolatey-license` package. If you don't currently have a license package, you can create one by following [the instructions](https://docs.chocolatey.org/en-us/c4b-environments/azure/license-update#creating-a-new-license-package). - -The Deployment Step included in this Deployment Plan upgrades, or installs if not present, the `chocolatey.license` package. The Deployment Plan -utilizes a schedule which will execute daily. - -Save the following as a `.json` file to import as a Chocolatey Central Management Deployment Plan: - - - -
- -```json -{ - "Name": "Upgrade License (Daily)", - "ScheduledDateTimeUtc": "2023-01-01T00:00:00Z", - "LastScheduledDateTimeUtc": null, - "RepeatPeriod": 1, - "ExecutionTimeoutInSeconds": 14400, - "RequiresApproval": false, - "DeploymentSteps": [ - { - "Name": "Update License", - "IsPrivileged": false, - "PlanOrder": 1, - "Script": "upgrade|chocolatey.license||false", - "ValidExitCodes": "0, 1605, 1614, 1641, 3010", - "ExecutionTimeoutInSeconds": 14400, - "FailOnError": true, - "RequireSuccessOnAllComputers": false, - "MachineContactTimeoutInMinutes": 0, - "DeploymentStepGroupIds": [] - } - ] -} -``` -
- -A weekly version of this Deployment Plan is available. Click the button below and save -the following as a `.json` file to import as a Chocolatey Central Management Deployment Plan: - - - -
- -```json -{ - "Name": "Upgrade License (Weekly)", - "ScheduledDateTimeUtc": "2023-01-01T00:00:00Z", - "LastScheduledDateTimeUtc": null, - "RepeatPeriod": 2, - "ExecutionTimeoutInSeconds": 14400, - "RequiresApproval": false, - "DeploymentSteps": [ - { - "Name": "Update License", - "IsPrivileged": false, - "PlanOrder": 1, - "Script": "upgrade|chocolatey.license||false", - "ValidExitCodes": "0, 1605, 1614, 1641, 3010", - "ExecutionTimeoutInSeconds": 14400, - "FailOnError": true, - "RequireSuccessOnAllComputers": false, - "MachineContactTimeoutInMinutes": 0, - "DeploymentStepGroupIds": [] - } - ] -} -``` -
- -#### Upgrading Chocolatey for Business Client Packages - -These Deployment Plans are examples of upgrading the Chocolatey for Business client packages. - -There are two example Deployment Plans here. They follow the instructions laid out on the [upgrading to Chocolatey v2](https://docs.chocolatey.org/en-us/guides/upgrading-to-chocolatey-v2-v6#upgrade-using-chocolatey-central-management-deployments) page. - -##### Upgrade the Chocolatey for Business Client Packages to the Latest 1.x Version. - -Save the following as a `.json` file to import as a Chocolatey Central Management Deployment Plan: - - - -
- -```json -{ - "Name": "Upgrade Chocolatey for Business Client to Latest 1.x", - "ScheduledDateTimeUtc": null, - "LastScheduledDateTimeUtc": null, - "RepeatPeriod": 0, - "ExecutionTimeoutInSeconds": 14400, - "RequiresApproval": false, - "DeploymentSteps": [ - { - "Name": "Upgrade to Latest 1.x Client Components", - "IsPrivileged": true, - "PlanOrder": 1, - "Script": "$Installed = choco list --local-only --limit-output | ConvertFrom-Csv -Delimiter '|' -Header 'Id','Version'\n$ChocolateyVersion = $Installed.Where{$_.Id -eq 'chocolatey'}.Version\n$AgentVersion = $Installed.Where{$_.Id -eq 'chocolatey-agent'}.Version\n$ExtensionVersion = $Installed.Where{$_.Id -eq 'chocolatey.extension'}.Version\n# We don't need to run this step if we're already on the latest 1.*\nif ([version]$ChocolateyVersion -ge '1.4.0' -and [version]$AgentVersion -ge '1.1.2' -and [version]$ExtensionVersion -ge '5.0.3') {\n exit 0\n}\n\n$delayInMinutes = 1\n# If using an internal repository to install Chocolatey Agent, replace `chocolatey.licensed` below\n# with the name or URL of your internally configured source.\nchoco upgrade chocolatey-agent --version=1.1.2 --source=\"'chocolatey.licensed'\"\n\n# Ensure the deployment task registers as failed if the installation failed, and skip registering the\n# scheduled task.\nif ($LASTEXITCODE -ne 0) {\n Write-Error 'The upgrade failed!'\n exit $LASTEXITCODE\n}\n\n# Restart the Agent service after the preset delay time via a scheduled task.\n$ScheduledTask = @{\n TaskName = \"Restart chocolatey-agent\"\n Description = \"Upgrade Chocolatey Agent\"\n Trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes($delayInMinutes)\n Action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument \"-WindowStyle Hidden -Command Restart-Service chocolatey-agent\"\n Principal = New-ScheduledTaskPrincipal -GroupId Administrators -RunLevel Highest\n Settings = New-ScheduledTaskSettingsSet -Hidden\n}\n\nRegister-ScheduledTask @ScheduledTask -Verbose:$false", - "ValidExitCodes": "0, 1605, 1614, 1641, 3010", - "ExecutionTimeoutInSeconds": 14400, - "FailOnError": true, - "RequireSuccessOnAllComputers": false, - "MachineContactTimeoutInMinutes": 0, - "DeploymentStepGroupIds": [] - }, - { - "Name": "Ensure Chocolatey CLI 1.4.0", - "IsPrivileged": true, - "PlanOrder": 2, - "Script": "choco upgrade chocolatey --version=1.4.0 --source=\"'chocolatey.licensed'\"\nexit $LASTEXITCODE", - "ValidExitCodes": "0, 1605, 1614, 1641, 3010", - "ExecutionTimeoutInSeconds": 14400, - "FailOnError": true, - "RequireSuccessOnAllComputers": false, - "MachineContactTimeoutInMinutes": 0, - "DeploymentStepGroupIds": [] - } - ] -} -``` -
- -##### Upgrade the Chocolatey for Business Client Packages to the Latest Version. - -Save the following as a `.json` file to import as a Chocolatey Central Management Deployment Plan: - - - -
- -```json -{ - "Name": "Upgrade Chocolatey for Business Client", - "ScheduledDateTimeUtc": null, - "LastScheduledDateTimeUtc": null, - "RepeatPeriod": 0, - "ExecutionTimeoutInSeconds": 14400, - "RequiresApproval": false, - "DeploymentSteps": [ - { - "Name": "Upgrade Chocolatey for Business Client Components", - "IsPrivileged": true, - "PlanOrder": 1, - "Script": "$delayInMinutes = 1\n\n# If using an internal repository to install Chocolatey Agent, replace `chocolatey.licensed` below\n# with the name or URL of your internally configured source.\nchoco upgrade chocolatey-agent --source=\"'chocolatey.licensed'\"\n\n# Ensure the deployment task registers as failed if the installation failed, and skip registering the\n# scheduled task.\nif ($LASTEXITCODE -ne 0) {\n Write-Error 'The upgrade failed!'\n exit $LASTEXITCODE\n}\n\n# Restart the Agent service after the preset delay time via a scheduled task.\n$ScheduledTask = @{\n TaskName = \"restart chocolatey-agent\"\n Description = \"Upgrade Chocolatey Agent\"\n Trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes($delayInMinutes)\n Action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument \"-WindowStyle Hidden -Command Restart-Service chocolatey-agent\"\n Principal = New-ScheduledTaskPrincipal -GroupId Administrators -RunLevel Highest\n Settings = New-ScheduledTaskSettingsSet -Hidden\n}\nRegister-ScheduledTask @ScheduledTask -Verbose:$false", - "ValidExitCodes": "0, 1605, 1614, 1641, 3010", - "ExecutionTimeoutInSeconds": 14400, - "FailOnError": true, - "RequireSuccessOnAllComputers": false, - "MachineContactTimeoutInMinutes": 0, - "DeploymentStepGroupIds": [] - }, - { - "Name": "Ensure Chocolatey CLI is Upgraded", - "IsPrivileged": true, - "PlanOrder": 2, - "Script": "choco upgrade chocolatey --source=\"'chocolatey.licensed'\"\nexit $LASTEXITCODE", - "ValidExitCodes": "0, 1605, 1614, 1641, 3010", - "ExecutionTimeoutInSeconds": 14400, - "FailOnError": true, - "RequireSuccessOnAllComputers": false, - "MachineContactTimeoutInMinutes": 0, - "DeploymentStepGroupIds": [] - } - ] -} -``` -
diff --git a/input/en-us/central-management/usage/examples/index.md b/input/en-us/central-management/usage/examples/index.md deleted file mode 100644 index 5e8bc0d054..0000000000 --- a/input/en-us/central-management/usage/examples/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 40 -xref: ccm-usage-examples -Title: Examples -Description: Suggested configurations, deployments, and usages for Chocolatey Central Management ---- \ No newline at end of file diff --git a/input/en-us/central-management/usage/index.md b/input/en-us/central-management/usage/index.md deleted file mode 100644 index 67a11af8f1..0000000000 --- a/input/en-us/central-management/usage/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 30 -xref: ccm-usage -Title: Usage -Description: Information about how to works with the different entities/functionality contained within Chocolatey Central Management ---- \ No newline at end of file diff --git a/input/en-us/central-management/usage/service/configuration.md b/input/en-us/central-management/usage/service/configuration.md deleted file mode 100644 index e52564fa2e..0000000000 --- a/input/en-us/central-management/usage/service/configuration.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -Order: 10 -xref: ccm-usage-service-configuration -Title: Configuration -Description: Information about the configuration options available for the CCM Service ---- - -## Chocolatey Central Management Service Configuration File - -> :choco-warning: **WARNING** -> -> Any changes to the `chocolatey-central-management.exe.config` file will require that the Chocolatey Central Management Service be restarted. - -There are a number of configuration options within the `chocolatey-central-management.exe.config` to control how the Chocolatey Central Management Service operates. - -### StaleActiveTimeoutBufferInSeconds - -The amount of time, in seconds, to add as a buffer when checking for stale active computers in Chocolatey Central Management. - -Default Value: `600` - -### UpdateKpisTimerIntervalInSeconds - -The amount of time, in seconds, of the interval between each execution of updating the Chocolatey Central Management KPIs (Key Performance Indicators). - -Default Value: `180` - -### CheckForComputerInformationMessagesToProcessTimerIntervalInSeconds - -The amount of time, in seconds, of the interval between checking for computer information messages to process in Chocolatey Central Management. - -Default Value: `30` - -### CheckForDeploymentStepResultMessagesToProcessTimerIntervalInSeconds - -The amount of time, in seconds, of the interval between checking for Deployment Step result messages to process in Chocolatey Central Management. - -Default Value: `30` - -### CheckForUnreachableComputersTimerIntervalInSeconds - -The amount of time, in seconds, of the interval between checking for unreachable computers in Chocolatey Central Management. - -Default Value: `180` - -### CheckForStaleActiveDeploymentComputersTimerIntervalInSeconds - -The amount of time, in seconds, of the interval between checking for stale active computers in Chocolatey Central Management. - -Default Value: `240` - -### CheckForScheduledDeploymentPlansTimerIntervalInSeconds - -The amount of time, in seconds, of the interval between checking for scheduled Deployment Plans in Chocolatey Central Management. - -Default Value: `60` - -### ComputerInformationMessagesFolderPath - -The path to the folder where incoming computer information messages will be stored. - -Default Value: `C:\ProgramData\chocolatey\services\computer_information_messages` - -### ComputerInformationMessagesProcessingFolderPath - -The path to the folder where computer information messages will be processed. - -Default Value: `C:\ProgramData\chocolatey\services\computer_information_messages_processing` - -### DeploymentStepResultMessagesFolderPath - -The path to the folder where incoming Deployment Step result messages will be stored. - -Default Value: `C:\ProgramData\chocolatey\services\deployment_step_result_messages` - -### DeploymentStepResultMessagesProcessingFolderPath - -The path to the folder where Deployment Step result messages will be processed. - -Default Value: `C:\ProgramData\chocolatey\services\deployment_step_result_messages_processing` - -### DeploymentStepResultMessagesFailedFolderPath - -The path to the folder where Deployment Step result messages that failed to process will be stored. _(Available since v0.8.0)_ - -Default Value: `C:\ProgramData\chocolatey\services\deployment_step_result_messages_failed` - -## Chocolatey Configuration File - -> :choco-info: **NOTE** -> -> When changes are made to these settings via the `choco config` command, there is no requirement to restart the CCM Service. These changes will be automatically picked up, and the necessary components within the CCM Service updated to use the changed values. - -### centralManagementServiceUrl - -The is the URL that is used by the Chocolatey Central Management Service to listen for incoming requests from the Chocolatey Agents installed on client machines. This configuration setting is used by both the Chocolatey Central Management Service, as well as Chocolatey Agent. - -Default Value: `https://:24020/ChocolateyManagementService` - -### centralManagementReceiveTimeoutInSeconds - -The amount of time, in seconds, that the Chocolatey Central Management Service connection can remain inactive, during which no application messages are received, before it is dropped. - -Default Value: `30` - -### centralManagementSendTimeoutInSeconds - -The amount of time, in seconds, that the Chocolatey Central Management Service will wait before raising an exception when attempting to perform a write operation. - -Default Value: `30` - -### centralManagementMaxReceiveMessageSizeInBytes - -The maximum size, in bytes, for a message that can be processed by the Chocolatey Central Management Service. - -Default Value: `2147483647` \ No newline at end of file diff --git a/input/en-us/central-management/usage/service/index.md b/input/en-us/central-management/usage/service/index.md deleted file mode 100644 index 20c8b0962c..0000000000 --- a/input/en-us/central-management/usage/service/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 20 -xref: ccm-usage-service -Title: Service -Description: Information about how to works with the different entities/functionality contained within Chocolatey Central Management Service ---- \ No newline at end of file diff --git a/input/en-us/central-management/usage/service/message-processing.md b/input/en-us/central-management/usage/service/message-processing.md deleted file mode 100644 index 3735991318..0000000000 --- a/input/en-us/central-management/usage/service/message-processing.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -Order: 20 -xref: ccm-usage-service-message-processing -Title: Message Processing -Description: Information about how messages are processed by the Chocolatey Central Management Service ---- - -> :choco-info: **NOTE** -> -> The message processing that is described below was introduced in version 0.4.1 of the Chocolatey Central Management Service. - -In order to ensure the safe delivery of messages from each Chocolatey Agent into the Chocolatey Central Management Service, a message processing system has been implemented. Rather than attempt to immediately add information into the database, each message is immediately stored to disk, and then processed via recurring jobs within the Chocolatey Central Management Service. This allows for the Service to easily handle bursts of messages that may happen as a result of a Deployment Step occurring on many machines, and then computers reporting into the Service. - -## Message Processing Folders - -The Chocolatey Central Management Service uses a number of different folders to process the incoming messages. These can be configured in the `chocolatey-central-management.exe.config` within the installation folder for the service. These folders are: - -* [ComputerInformationMessagesFolderPath](xref:ccm-usage-service-configuration#computerinformationmessagesfolderpath) -* [ComputerInformationMessagesProcessingFolderPath](xref:ccm-usage-service-configuration#computerinformationmessagesprocessingfolderpath) -* [DeploymentStepResultMessagesFolderPath](xref:ccm-usage-service-configuration#deploymentstepresultmessagesfolderpath) -* [DeploymentStepResultMessagesProcessingFolderPath](xref:ccm-usage-service-configuration#deploymentstepresultmessagesprocessingfolderpath) -* [DeploymentStepResultMessagesFailedFolderPath](xref:ccm-usage-service-configuration#deploymentstepresultmessagesfailedfolderpath) - -As new messages, both computer information and Deployment Step results, arrive at the Chocolatey Central Management Service, they are immediately stored into the `*MessagesFolderPath` folders. Then as the service begins to process these messages, they are moved into the `*MessageProcessingFolderPath` folders, and once they are processed, the stored messages are deleted. - -## Message Processing Folder Permissions - -During start up of the Chocolatey Central Management Service, it will ensure that all required folders are created (based on the configured values above). In addition, it will ensure, for security purposes, that only the user account that is currently running the Chocolatey Central Management Service has read/write permissions to these folders. By default, this will be the ChocolateyLocalAdmin user, which Chocolatey creates as part of the installation process. If an additional account is used to run the Chocolatey Central Management Service, then this account, and only this account, will be provided read/write permissions to these folders. - -## Poison Messages - -Starting in version 0.8.0 of the Chocolatey Central Management service there is now an additional folder for Deployment Step messages. Processed messages that failed to update the status of the Deployment Step will be moved to the folder specified in [`DeploymentStepResultMessagesFailedFolderPath`](xref:ccm-usage-service-configuration#deploymentstepresultmessagesfailedfolderpath) after the update has been tried 3 times. Files in this directory are not deleted by the Chocolatey Central Management service. - -See the additional information below for computers which have reported in the status of their Chocolatey packages, or for older versions of Chocolatey Central Management service. - -If there is an error during the processing of a message, the message will not be deleted from the `*MessageProcessingFolderPath`. As a result, the message will attempt to be processed again. - -In the unlikely event that there is something "wrong" with the message, and it can't be processed, it will become what is known as a "poison message" and it will remain in the queue indefinitely, attempting to be processed each cycle. If/when this happens, it will be necessary to remove this message from the `*MessageProcessingFolderPath` folder. - -To do this, first stop the Chocolatey Central Management Service. Due to the permissions that are applied on these folders, it will first be necessary for an administrator of the machine to take ownership of the folder that contains the message(s), and to either: - -* move the message to another location -* delete the message - -Once any poison messages have been removed, the Chocolatey Central Management Service should be restarted, and the permissions for those folders will be reapplied. \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/administration/audit-logs.md b/input/en-us/central-management/usage/website/administration/audit-logs.md deleted file mode 100644 index 7a6e2b71bf..0000000000 --- a/input/en-us/central-management/usage/website/administration/audit-logs.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -Order: 40 -xref: ccm-administration-audit-logs -Title: Audit Logs -Description: Information about using the audit logs within the Chocolatey Central Management Administration section ---- - -## Operation logs - -The Chocolatey Central Management Website stores a lot of information about the operations that have been performed on it. - -It is possible to search for operations that have happened using a number of different filters: - -- Date range -- User name - -Expanding the `Show advanced filters` section displays the following filters: - -- Service -- Duration -- Action -- Error state -- Browser - -Once the required filters have been set, pressing the `Refresh` button will show the available results. - -![Operation logs tab within the Audit logs section of the Administration | Settings page](/assets/images/ccm-playwright/administration/audit-logs/left-menu-active.png) - -It is possible to see all available information for an operation by clicking the :mag: button to the left-hand side of the table. - -If required, the available results can be exported to an Excel document using the `Export | Export to Excel` button. -This will generate a file named something similar to the following `Chocolatey_AuditLogs_20231122_095144.xlsx`. - -The length of time that Operation logs are stored within the Chocolatey Central Management Website can be configured in the [Retention Policies](xref:ccm-administration-settings-retention#audit-retention) Settings tab. - -## Change logs - -> :choco-warning: **WARNING** -> -> This section of the Chocolatey Central Management Website does not actually provide any functionality, and will be removed in a future version. \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/administration/index.md b/input/en-us/central-management/usage/website/administration/index.md deleted file mode 100644 index 7da82e7f3d..0000000000 --- a/input/en-us/central-management/usage/website/administration/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 70 -xref: ccm-administration -Title: Administration -Description: How to configure the different administration sections of Chocolatey Central Management ---- \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/administration/maintenance.md b/input/en-us/central-management/usage/website/administration/maintenance.md deleted file mode 100644 index d7c0d3fbe0..0000000000 --- a/input/en-us/central-management/usage/website/administration/maintenance.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -Order: 50 -xref: ccm-administration-maintenance -Title: Maintenance -Description: Information about using the maintenance functions within the Chocolatey Central Management Administration section. ---- - -## Caches - -To improve overall performance of the Chocolatey Central Management Website, a number of different caches are used. - -If/when required, these caches can be cleared, either individually, or all at once. - -![Caches tab within the Maintenance section of the Administration | Settings page](/assets/images/ccm-playwright/administration/maintenance/left-menu-active.png) - -## Website Logs - -It is possible to review, and download, the logs for the Chocolatey Central Management Website. - -Clicking the `Download all` button will download all the available Website logs in a `WebSiteLogs.zip` file. - -Clicking the `Refresh` button will load any additional logs that have been created since the page was first opened. - -![Websites Logs tab within the Maintenance section of the Administration | Settings page](/assets/images/ccm-playwright/administration/maintenance/tab-website-logs.png) \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/administration/roles.md b/input/en-us/central-management/usage/website/administration/roles.md deleted file mode 100644 index 572006aaf5..0000000000 --- a/input/en-us/central-management/usage/website/administration/roles.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -Order: 10 -xref: ccm-administration-roles -Title: Roles -Description: Information about configuring roles within the Chocolatey Central Management Administration section ---- - -Chocolatey Central Management's roles are the basis for setting collections of permissions that can be assigned to specific users within Chocolatey Central Management. - -Roles can be accessed by going to Administration on the left-hand navigation and selecting roles. - -![Roles menu entry on the CCM Dashboard](/assets/images/ccm-playwright/dashboard/left-menu-nested-roles.png) - -## Creating a Role - -On the main roles page, select the **+ Create New Role** button. - -![Create New Role button on the Roles page](/assets/images/ccm-playwright/administration/roles/button-create-new-role.png) - -You will then be presented with the Role properties window where you can enter the name for the new role. You also have the option to make your new role the Default which will be added to all new users by default. - -![Creating New Role Setting Role Properties](/assets/images/ccm-playwright/administration/roles/modal-new-role-tab-role.png) - -Next you'll want to click over to Permissions. This window will allow you to select what specific permissions you wish to give your new role. - -![Creating New Role Setting Permissions](/assets/images/ccm-playwright/administration/roles/modal-new-role-tab-permissions.png) - -Click :floppy_disk: **Save** to close the window and create the new role. - -## Editing a Role - -> :choco-info: **NOTE** -> -> If you do not see the **Edit** menu entry or the :gear: **Actions** buttons, please see your Administrator to determine if your account has the _Edit Roles_ permission. - -On the main Roles page, find the role you want to edit. -You can also use _Select Permissions (0)_ to filter the Roles listed based on them having the permissions you select. - -Select the :gear: **Actions** button on the left-hand side of the role, and then select **Edit** to open the _Edit Group_ window. - -![Edit menu entry in role actions flyout menu](/assets/images/ccm-playwright/administration/roles/table-row-button-action-dropdown-menu-edit.png) - -From the **Edit Role** window, you can modify the name, set it to be the Default role, and edit its permissions. - -## Deleting a Role - -> :choco-info: **NOTE** -> -> If you do not see the **Delete** menu entry or the :gear: **Actions** buttons, please see your Administrator to determine if your account has the _Edit Roles_ permissions. -> -> Roles labelled **Static** cannot be deleted. -> -> You cannot delete a Role if the account you are using also has the Role assigned to it. - -On the main Roles page, find the role you want to delete. You can also use _Select Permissions (0)_ to filter the roles listed based on permission. Similar to the [Edit Role](#editing-a-role) action, select the :gear: **Actions** button on the left-hand side of the role, and select **Delete**. You will be prompted to confirm the deletion. - -## Pre-Configured Roles - -When first browsing to the Roles page, you'll be presented with 4 pre-configured roles that are built-in to Chocolatey Central Management. - -* CCM Admin -* CCM User -* CCM Deployment -* CCM Deployment Privileged - -These pre-configured roles are labeled **Static** and cannot be deleted. They can however be edited by name, default role selection, and permissions. - -We recommend you review the permissions these roles have. Then edit them, if needed, to work within your environment. - -## Related Topics - -* [Chocolatey Central Management](xref:central-management) -* [Chocolatey Central Management - Deployments](xref:ccm-deployments) -* [Chocolatey Central Management - Reports](xref:ccm-reports) diff --git a/input/en-us/central-management/usage/website/administration/sensitive-variables.md b/input/en-us/central-management/usage/website/administration/sensitive-variables.md deleted file mode 100644 index 8febd543fd..0000000000 --- a/input/en-us/central-management/usage/website/administration/sensitive-variables.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -Order: 30 -xref: ccm-administration-sensitive-variables -Title: Sensitive Variables -Description: Information on sensitive variables within Chocolatey Central Management -RedirectFrom: en-us/central-management/usage/website/sensitive-variables ---- - -Chocolatey Central Management gives you the ability to create sensitive variables for use in Deployment Steps. - -The **Sensitive Variables** page can be accessed from the Administration section of Chocolatey Central Management. The page is only visible to users who have permissions to create or delete sensitive variables. - -![Chocolatey Central Management dashboard, arrow pointing to Sensitive Variables menu in the left sidebar entry.](/assets/images/ccm-playwright/dashboard/left-menu-nested-sensitive-variables.png) - -## Creating a new Sensitive Variable - -1. From the Chocolatey Central Management Dashboard, select `Administration` > `Sensitive Variables` from the left sidebar. - - ![Chocolatey Central Management dashboard, arrow pointing to Sensitive Variables menu in the left sidebar entry.](/assets/images/ccm-playwright/dashboard/left-menu-nested-sensitive-variables.png) -1. Select the :heavy_plus_sign: **Create new sensitive variable** button at the top of the page. - - ![CCM Sensitive Variables page, arrow pointing to Create new sensitive variable button](/assets/images/ccm-playwright/administration/sensitive-variables/button-create-new-sensitive-variable.png) -1. Fill in the details and click Save. - - ![Fill in Sensitive Variables information](/assets/images/ccm-playwright/administration/sensitive-variables/modal-new-sensitive-variable.png) - -Alternatively, variables can also be added from an Deployment Step Advanced script by clicking the :heavy_plus_sign: in the upper right corner. - -![Sensitive Variables Added from the Advanced script of a Deployment Step](/assets/images/ccm-playwright/deployment-plans/edit/modal-step-button-create-sensitive-variable.png) - -## Adding Sensitive Variables to scripts - - - -1. In an Advanced script of a Deployment Step, select the variable to insert from the Sensitive Variables drop down. - -![Deployment Step Advanced script, with an arrow pointing to the Sensitive Variables selection dropdown.](/assets/images/ccm-playwright/deployment-plans/edit/modal-step-advanced-command-select-sensitive-variable.png) - -## Deleting Sensitive Variables - -1. From the Chocolatey Central Management Dashboard, select `Administration` > `Sensitive Variables` from the left sidebar. - - ![Central Management dashboard, arrow pointing to Sensitive Variables menu in the left sidebar entry on the CCM Dashboard](/assets/images/ccm-playwright/dashboard/left-menu-nested-sensitive-variables.png) -1. Select :wastebasket: **Delete** beside the Sensitive Variable you wish to delete. - - ![Sensitive Variables page with arrow to a delete button](/assets/images/ccm-playwright/administration/sensitive-variables/button-quick-action-delete.png) - -## Editing / Changing Sensitive Variables - -You cannot change or edit a Sensitive Variable directly. If you need to change the value a Sensitive Variable has, please [delete it](#deleting-sensitive-variables) and [create it](#creating-a-new-sensitive-variable) again. diff --git a/input/en-us/central-management/usage/website/administration/settings/dashboard.md b/input/en-us/central-management/usage/website/administration/settings/dashboard.md deleted file mode 100644 index c45889b977..0000000000 --- a/input/en-us/central-management/usage/website/administration/settings/dashboard.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -Order: 13 -xref: ccm-administration-settings-dashboard -Title: Dashboard -Description: Information about setting Dashboard settings within the Administration Settings screen ---- - -> :choco-info: **NOTE** -> -> This feature is available in Chocolatey Central Management starting with version 0.12.0. - -On the [Chocolatey Central Management Dashboard](xref:ccm-dashboard) there is a count of the `Total Stale Computers`. This is defined as `the total number of Computers that haven't reported into Chocolatey Central Management in the last 180 days.`. Here 180 is the default value, but you can change this by using the following steps: - -1. Open the Chocolatey Central Management Site in the browser. -1. Login with the `ccmadmin` user. -1. In the left-hand menu click on `Administration` and then `Settings`. -1. Click on the `Dashboard` tab in the `Settings` screen. - - ![Chocolatey Central Management Dashboard Settings](/assets/images/ccm-playwright/administration/settings/tab-dashboard.png) - -1. Adjust the `Amount of time, in Days, before being notified of Computers not reporting in`. -1. Click the `Save All` button to save changes. - -> :choco-info: **NOTE** -> -> When the [Stale Computer Retention Policy](xref:ccm-administration-settings-retention#stale-computer-retention) is enabled, it is not possible to set the `Amount of time, in Days, before being notified of Computers not reporting in` for the Dashboard to a number that is lower than what is currently configured for the `Amount of time, in Days, to keep stale Computers before deleting` setting, and vice versa. If this is attempted, a validation warning will be shown. - -> :choco-info: **NOTE** -> -> When upgrading to Chocolatey Central Management 0.12.0, if the [Stale Computer Retention Policy](xref:ccm-administration-settings-retention#stale-computer-retention) is enabled, if the current value for `Amount of time, in Days, to keep stale Computers before deleting` is less than the default value for `Amount of time, in Days, before being notified of Computers not reporting in`, a change will be made to the default value to make it half of the configured value for `Amount of time, in Days, to keep stale Computers before deleting`. \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/administration/settings/email.md b/input/en-us/central-management/usage/website/administration/settings/email.md deleted file mode 100644 index 4ef19a28b4..0000000000 --- a/input/en-us/central-management/usage/website/administration/settings/email.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -Order: 40 -xref: ccm-administration-settings-email -Title: Email (SMTP) -Description: Information about using up email settings within the Administration Settings screen ---- - -The CCM Site needs to be able to send email for certain actions. For example, when a new user is registering with the system, or when sending out forgotten password emails. Valid SMTP Configuration has to be provided in order for these emails to be sent out. Follow these steps to configure SMTP for CCM. - -1. Open the CCM Site in the browser -1. Login with the `ccmadmin` user -1. In the left-hand menu click on `Administration` and then `Settings` -1. Click on the `Email (SMTP)` tab in the `Settings` screen - - ![Chocolatey Central Management Email Settings](/assets/images/ccm-playwright/administration/settings/tab-email-(smtp).png) - -1. Add the SMTP settings for your environment. If you uncheck the `Use default credentials` checkbox, you will need to provide the `Domain name`, `User name` and `SMTP Password` for a user that is permitted to send email via the system that is being used. -1. Click the `Save All` button to save changes -1. Change the email address to go to your email address -1. Click the `Send Test Email` button and ensure that an email is received correctly - -You should receive a notification similar to this: - -![Test email sent successfully](/assets/images/ccm-playwright/administration/settings/email-(smtp)-toast-success.png) - -> :choco-warning: **WARNING** -> -> If you leave either the `Default from (sender) email address` or `Default from (sender) display name` with their default values, you will see an error when an email is attempted to be sent via the system. \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/administration/settings/encryption-passphrase.md b/input/en-us/central-management/usage/website/administration/settings/encryption-passphrase.md deleted file mode 100644 index 699825120d..0000000000 --- a/input/en-us/central-management/usage/website/administration/settings/encryption-passphrase.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -Order: 70 -xref: ccm-encryption-passphrase -Title: Encryption Passphrase -Description: Information on the Encryption Passphrase within Chocolatey Central Management -RedirectFrom: en-us/central-management/usage/website/encryption-passphrase ---- - -Starting in Chocolatey Central Management 0.7.0 we are providing the ability to control the passphrase that is used when encrypting both secret values and certain requests that happen between the website and the service. - -The encryption passphrase can be changed in Chocolatey Central Management by accessing the `Administrator -> Settings` section and selecting the `Security` tab. The settings for the encryption passphrase will only be visible to users who are a member of the CCM Administrator role. - -> :choco-danger: **IMPORTANT** -> -> We recommend this passphrase is set as soon as possible. However, a user who is a member of the CCM Administrator role will be able to defer this for 4 logins. On the 5th login they will be restricted to only being able to set the passphrase. - -> :choco-warning: **WARNING** -> -> Changing the encryption passphrase will invalidate the links in Email Activation and Password Resets emails sent out prior to the change. The user clicking on the invalid link will be notified of this, and will be requested to enter their information again to have a new email sent. - -## Set the encryption passphrase for the first time { #set-the-encryption-passphrase-for-the-first-time } - -> :choco-warning: **WARNING** -> -> Once the passphrase has been changed and saved, there will be a short delay while both the website and the API are updated. During that time they will be unavailable for any other use and browsing the website or calling the API may result in a `500 - Internal Server Error` response. - -1. Navigate to the `Administrator -> Settings` section of Central Management, and click on the `Security` tab to show the location that a new passphrase can be set (_New `CCM Admin` Logins will be redirected to this location_). - - ![Chocolatey Central Management Settings, encryption passphrase location](/assets/images/ccm-playwright/administration/settings/security-alert-new-passphrase-warning.png) - -2. Enter the passphrase to use in the box labeled `New Passphrase`. - - > :choco-info: **NOTE** - > - > The new passphrase must meet the following requirements: - > - > 1. A length equal to, or higher than, 5 characters. - > 2. At least 1 lowercase character (`a-z`). - > 3. At least 1 uppercase character (`A-Z`). - > 4. At least 1 digit (`0-9`). - > 5. At least 1 alpha numeric character. -3. Enter the same passphrase in the box labeled `Confirm New Passphrase`. - - > :choco-warning: **WARNING** - > - > Make sure to save the passphrase in a secure location as it will be needed if there is a need to change it again in the future. - > Chocolatey Software, Inc. will not be responsible for any misplaced passphrases or restoring the database if the passphrase has been forgotten or lost. -4. Save the changes using the `Save all` button located at the top of the page. - - > :choco-warning: **WARNING** - > - > This will take between 5 and 10 seconds but could take more depending on performance. - > During this time it is not recommended to navigate to any other pages or make any API calls as they may result in an error. - > A dialog to refresh the page will be displayed once the changes have completed. -5. Users following links for email activation or password resets will need to re-enter their information to have a new email sent. - - ![Chocolatey Central Management, invalid Forgot Password link ](/assets/images/ccm-playwright/account/forgot-password/alert-invalid-link.png) - ![Chocolatey Central Management, invalid Email Activation link](/assets/images/ccm-playwright/account/email-activation/alert-invalid-link.png) - -## Update the encryption passphrase - -The same procedure can be followed as was detailed in the [`Set the encryption passphrase for the first time`](#set-the-encryption-passphrase-for-the-first-time) section above. -The only difference is that the current passphrase, as well as the new passphrase, will have to be entered. - -## Additional warnings that may be seen - -We have added a number of warnings to help highlight that changes need to be made, where and by whom. Please see these screenshots below. - -- Before a user is logged in, they will see a warning on the login screen confirming that additional changes need to be made by a user who is a member of the CCM Administrator role. - - ![Chocolatey Central Management Login warning, pointing out changes are needed](/assets/images/ccm-playwright/account/login/alert-additional-settings.png) -- If a user is logged in, but is not in the CCM Administrator role, the same warning is displayed to the user. - - ![Chocolatey Central Management Dashboard warning for normal users](/assets/images/ccm-playwright/dashboard/alert-passphrase-admin.png) -- A user that is a member of the CCM Administrator role, will be redirected to set the encryption passphrase, when they log in. - - ![Chocolatey Central Management Settings, encryption passphrase location](/assets/images/ccm-playwright/administration/settings/security-alert-new-passphrase-warning.png) - -- A user that is a member of the CCM Administrator role, will be able to navigate to other sections of Chocolatey Central Management when they have not set the encryption passphrase and have logged in less than 5 times. - - ![Chocolatey Central Management Dashboard warning on Administrators](/assets/images/ccm-playwright/dashboard/alert-passphrase-user.png) - -- On the 5th and subsequent logins, a user who is a member of the CCM Administrator role will be redirected to set the encryption passphrase and will not be able to navigate to other sections of Chocolatey Central Management until the passphrase has been set. - > :choco-info: **NOTE** - > - > A user who is not a member of the CCM Administrators role will still be available to use Chocolatey Central Management website and API, as normal . - - ![Chocolatey Central Management Settings, encryption passphrase required](/assets/images/ccm-playwright/administration/settings/security-alert-new-passphrase-danger.png) - -## FAQ - -### What is the encryption passphrase? - -The encryption passphrase is the password (along with a salt value) that will be used to encrypt sensitive settings in the database, as well as links in Password Reset and Email Activation emails. - -### What items are encrypted using the passphrase? - -The following items are encrypted using the passphrase: - -- [`Sensitive Variables`](xref:ccm-administration-sensitive-variables). -- SMTP and LDAP passwords. -- Links used in Email Activation and Password Reset emails. -There are also some of the requests used when browsing the web site, and making API requests that also encrypt/decrypt values using the same passphrase. - -### Why do I need to set a passphrase? - -We have enhanced the security of fields stored in the database to use encryption that requires a unique passphrase that you control and can change if/when needed. This allows you to ensure the encryption passphrase is always secure, regularly updated and meets the standards of your organization. diff --git a/input/en-us/central-management/usage/website/administration/settings/general.md b/input/en-us/central-management/usage/website/administration/settings/general.md deleted file mode 100644 index 13e70c187c..0000000000 --- a/input/en-us/central-management/usage/website/administration/settings/general.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -Order: 10 -xref: ccm-administration-settings-general -Title: General -Description: Information about using up general settings within the Administration Settings screen ---- - -The Administration Settings page loads the General tab by default. This page is used to set the default timezone. - -If a user does not set their own timezone for display from `My Settings`, then the selected timezone will be used for the display of all times. - -![General Settings Administration page of Chocolatey Central Management](/assets/images/ccm-playwright/administration/settings/tab-general.png) diff --git a/input/en-us/central-management/usage/website/administration/settings/index.md b/input/en-us/central-management/usage/website/administration/settings/index.md deleted file mode 100644 index 7f42b250e1..0000000000 --- a/input/en-us/central-management/usage/website/administration/settings/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 60 -xref: ccm-administration-settings -Title: Settings -Description: How to configure the different settings of Chocolatey Central Management ---- \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/administration/settings/retention.md b/input/en-us/central-management/usage/website/administration/settings/retention.md deleted file mode 100644 index c9fd5bc0a8..0000000000 --- a/input/en-us/central-management/usage/website/administration/settings/retention.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -Order: 50 -xref: ccm-administration-settings-retention -Title: Retention Policies -Description: Information about using retention settings within the Administration Settings screen -RedirectFrom: - - en-us/central-management/usage/website/administration/settings/audit-retention - - en-us/central-management/usage/website/administration/settings/stale-computer-deletion ---- - -Chocolatey Central Management has a number of settings that allow you to adjust various retention periods. By default, only the Audit Retention policy is enabled. - -If you want to change these settings, follow these steps: - -1. Open the CCM Site in the browser. -1. Login with the `ccmadmin` user. -1. In the left-hand menu click on `Administration` and then `Settings`. -1. Click on the `Retention Policies` tab - -1. Modify the settings as required -1. Click the `Save All` button at the bottom left of the page to save your settings. - - -As noted in the User Interface, any modifications to this section of the settings will require the Web Application to be restarted. This can be completed by doing the following: - -1. Get direct access to the machine that is hosting the CCM Web Application -1. Open an administrative PowerShell session -1. Run the following commands: - ```powershell - Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Force - Stop-Website -Name ChocolateyCentralManagement - Restart-WebAppPool -Name ChocolateyCentralManagement - Start-Website -Name ChocolateyCentralManagement - ``` - -## Audit Retention - -> :choco-warning: **WARNING** -> -> **BREAKING CHANGE** -> -> This feature was added, as a breaking change, in version 0.6.0 of Chocolatey Central Management. Audit Retention is enabled by default, and will immediately start truncating the audit log table as soon as it is installed. -> If you require keeping all audit logs, we would recommend that you first back up the CCM database before applying the new version. - -In an attempt to control the size of the Chocolatey Central Management database, it is possible to control the retention policy for the audit logs table within the application. - -By default, Audit Retention is enabled, and any logs that are older than 30 days will automatically be removed. - -![Audit Retention Settings](/assets/images/ccm-playwright/administration/settings/retention-policies-checkbox-enable-audit-retention.png) - -## Stale Computer Retention - - -> :choco-info: **NOTE** -> -> This feature is available in Chocolatey Central Management starting with version 0.10.0. - -In Chocolatey Central Management, a stale computer is one which hasn't reported in for a long period of time. This could be perfectly normal, but it could also be a sign that this computer is no longer active, and should be removed. This is something that can be done manually, given the correct permissions, from the [computers page](xref:ccm-computers#removing-a-computer-from-central-management), however, enabling this setting automatically removes stale computers from Chocolatey Central Management. - -By default, Stale Computer Deletion is disabled. When it is enabled, computers that haven't reported into Chocolatey Central Management within the set timeframe (the default is 365 days) will be removed. - -![Stale Computer Deletion Settings](/assets/images/ccm-playwright/administration/settings/retention-policies-checkbox-enable-stale-computer-retention.png) - -## Deployment Plan Retention - -> :choco-info: **NOTE** -> -> This feature is available in Chocolatey Central Management starting with version 0.11.0. - -Chocolatey Central Management has the ability to automatically archive or delete Deployment Plans that have reached a completion state. - - -By default, Deployment Plan Retention is disabled for both archiving and deleting. When it is enabled, Deployment Plans that have completed beyond the set timeframe (the default is 30 days) will be archived, or deleted. If both archive and delete are enabled, the delete period will be considered the combination of the archive and the delete. - - - -![Deployment Plan Retention Settings](/assets/images/ccm-playwright/administration/settings/retention-policies-checkbox-enable-deployment-plan-retention.png) diff --git a/input/en-us/central-management/usage/website/administration/settings/security.md b/input/en-us/central-management/usage/website/administration/settings/security.md deleted file mode 100644 index c529fcd175..0000000000 --- a/input/en-us/central-management/usage/website/administration/settings/security.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -Order: 30 -xref: ccm-administration-settings-security -Title: Security -Description: Information about using up security settings within the Administration Settings screen ---- - -## Two Factor Login - -> :choco-info: **NOTE** -> -> This feature is available in Chocolatey Central Management starting with version 0.10.0. - -By default, Two Factor Login is disabled in Chocolatey Central Management. - -If you want to change these settings, follow these steps: - -1. Open the CCM Site in the browser. -1. Login with the `ccmadmin` user. -1. In the left-hand menu click on `Administration` and then `Settings`. -1. Click on the `Security` tab -1. Either enable, or disable, the `Enable two factor user login` checkbox as required. - - ![Chocolatey Central Management Security Two Factor Login Settings](/assets/images/ccm-playwright/administration/settings/security-checkbox-enable-two-factor-authentication.png) - -1. If enabled, choose whether to `Enable email verification` and `Allow to remember browser. If you allow this, users can select to remember browser to skip second time two factor login for the same browser.` -1. Click the `Save All` button at the top right of the page to save your settings. - -> :choco-info: **NOTE** -> -> If you disable the `Enable email verification` option, this is the same as disabling all two factor login. In future versions of Chocolatey Central Management, there will be additional methods of verification on top of only email, this is why there is a checkbox for it currently. - -Once enabled, any user logging into the Chocolatey Central Management website will be presented with this screen, where they will have the allotted time to enter the security code which will have been sent to the email address associated with their account. - -The `Remember this browser` checkbox is what can be enabled/disabled in step 6 above. If the user chooses to enable this setting, a cookie will be created and stored in the browser, meaning that they will not be promoted for a two factor login security code on this browser again. \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/administration/settings/user-management.md b/input/en-us/central-management/usage/website/administration/settings/user-management.md deleted file mode 100644 index 381c90d643..0000000000 --- a/input/en-us/central-management/usage/website/administration/settings/user-management.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -Order: 20 -xref: ccm-administration-settings-user-management -Title: User Management -Description: Information about using up user management settings within the Administration Settings screen ---- - -## LDAP Configuration - -> :choco-info: **NOTE** -> -> The Central Management Server must be joined to the Active Directory Domain. - -1. Open the CCM Site in the browser. -1. Login with the `ccmadmin` user. -1. In the left-hand menu click on `Administration` and then `Settings`. -1. Click on the `User management` tab in the `Settings` screen. -1. Under LDAP Setting click the `Enable LDAP Authentication` button. -1. Fill in your FQDN for the `Domain name` field and the `User name` field with an active directory account that has access to query user accounts within your active directory environment. - - ![CCM LDAP Setup](/assets/images/ccm-playwright/administration/settings/user-management-checkbox-enable-ldap.png) - -1. Click the `Update LDAP Password` button to open a modal window to allow you to enter/confirm the password that is to be used. - - ![Update LDAP Password](/assets/images/ccm-playwright/administration/settings/user-management-modal-ldap-password.png) - -1. Click the `Save` button -1. Click the `Save All` button at the top right of the page to save your settings. - -> :choco-info: **NOTE** -> -> In order for LDAP authentication to succeed in versions of Central Management 0.3.1 and lower -> an Email Address, Surname, and GivenName must be configured on the properties of the Active Directory user you are -> attempting to use for login. If any of these fields are empty, errors will be encountered when attempting to login -> to the Central Management application. \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/administration/settings/website.md b/input/en-us/central-management/usage/website/administration/settings/website.md deleted file mode 100644 index b3fb5898f8..0000000000 --- a/input/en-us/central-management/usage/website/administration/settings/website.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -Order: 15 -xref: ccm-administration-settings-website -Title: Website -Description: Information about setting Website settings within the Administration Settings screen ---- - -> :choco-info: **NOTE** -> -> This feature is available in Chocolatey Central Management starting with version 0.11.0. - -When Chocolatey Central Management sends out emails, they need to know the hostname of the CCM server in order to be able to correctly link back to the Chocolatey Central Management website. When Chocolatey Central Management is installed, it tries to determine the website host and stores it in the Website Settings as the `Web site root address`. If the hostname used to access the Chocolatey Central Management website changes, you will want to update this setting. Follow these steps to configure the Web site root address for Chocolatey Central Management. - -1. Open the CCM Site in the browser. -1. Login with the `ccmadmin` user. -1. In the left-hand menu click on `Administration` and then `Settings`. -1. Click on the `Website` tab in the `Settings` screen. - - ![Chocolatey Central Management Website Settings](/assets/images/ccm-playwright/administration/settings/tab-website.png) - -1. Adjust the Web site root address. -1. Click the `Save All` button to save changes. - -As noted in the User Interface, any modifications to this section of the settings will require the Chocolatey Central Management Service to be restarted. This can be completed by doing the following: - -1. Get direct access to the machine that is hosting the Chocolatey Central Management Service. -1. Open an administrative PowerShell session. -1. Run the following command: `Restart-Service chocolatey-central-management`. diff --git a/input/en-us/central-management/usage/website/administration/users.md b/input/en-us/central-management/usage/website/administration/users.md deleted file mode 100644 index a96b9de2f7..0000000000 --- a/input/en-us/central-management/usage/website/administration/users.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -Order: 20 -xref: ccm-administration-users -Title: Users -Description: Information about configuring Users within the Chocolatey Central Management Administration section ---- - -In Chocolatey Central Management, Users are people who are given access to login in, and perform operations. - -Users can be accessed by going to Administration on the left-hand navigation and selecting Users. - -![Users menu entry on the Chocolatey Central Management Dashboard](/assets/images/ccm-playwright/dashboard/left-menu-nested-users.png) - -## Creating a User - -> :choco-info: **NOTE** -> -> If you do not see the **+ Create new user** button, please see your Administrator to determine if your account has the _Creating new user_ permission. - -On the main Users page, select the **+ Create New User** button. - -![Create New User button on the Users page](/assets/images/ccm-playwright/administration/users/button-create-new-user.png) - -You will then be presented with the `Create New User` window where you can enter all the information for the User, including `First Name`, `Email address`, etc. - -![Creating New User Setting User Properties](/assets/images/ccm-playwright/administration/users/modal-new-user-tab-information.png) - -Next you'll want to click over to `Roles`. This window will allow you to select what specific [Roles](xref:ccm-administration-roles) you wish to give your new User. - -![Creating New User Setting Roles](/assets/images/ccm-playwright/administration/users/modal-new-user-tab-roles.png) - -Click :floppy_disk: **Save** to close the window and create the new User. -A green toast notification will be shown once the operation completes successfully. - -## Editing a User - -> :choco-info: **NOTE** -> -> If you do not see the **Edit** menu entry or the :gear: **Actions** buttons, please see your Administrator to determine if your account has the _Editing user_ permission. - -On the main Users page, [find](#searching-for-a-user) the User you want to edit. -Select the :gear: **Actions** button on the left-hand side of the User, and then select **Edit** to open the _Edit User_ window. - -![Edit menu entry in User actions flyout menu](/assets/images/ccm-playwright/administration/users/table-row-button-action-dropdown-menu-edit.png) - -From the **Edit Role** window, you can modify all the properties for a User, for example, `First Name`, `Phone number`, etc. In addition, you can alter the [Roles](xref:ccm-administration-roles) associated with the User. - -Once modifications are complete, click the :floppy_disk: **Save** button. -A green toast notification will be shown once the operation completes successfully. - -## Fine grained permissions - -In addition to configuring a set of Roles for an individual User, so can set speicial permissions for an individual User. - -On the main Users page, [find](#searching-for-a-user) the User you want to edit. -Select the :gear: **Actions** button on the left-hand side of the User, and then select **Permission** to open the _Permissions_ window. - -![Permissions menu entry in User actions flyout menu](/assets/images/ccm-playwright/administration/users/modal-permissions.png) - -From the tree of permissions, check/uncheck the permissions that are needed. - -Once modifications are complete, click the :floppy_disk: **Save** button. -A green toast notification will be shown once the operation completes successfully. - -## Deleting a User - -> :choco-info: **NOTE** -> -> If you do not see the **Delete** menu entry or the :gear: **Actions** buttons, please see your Administrator to determine if your account has the _Deleting user_ permission. - -On the main Users page, [find](#searching-for-a-user) the User that needs to be deleted. -Select the :gear: **Actions** button on the left-hand side of the User, and then select **Delete**. -A prompt will be shown asking `Are you sure?`. -Click `Cancel` to not continue with the operation. -Click `Yes` to proceed with the operation. -A green toast notification will be shown once the operation completes successfully. - -## Unlocking a User - -> :choco-info: **NOTE** -> -> If you do not see the **Unlock** menu entry or the :gear: **Actions** buttons, please see your Administrator to determine if your account has the _Editing user_ permission. - -If a User enters the wrong login information 5 times, their account will become locked. -To allow them to attempt to login again, the account will need to be unlocked. -On the main Users page, [find](#searching-for-a-user) the User that is locked out. -Select the :gear: **Actions** button on the left-hand side of the User, and then select **Unlock**. -A green toast notification will be shown once the operation completes successfully. - -## Searching for a User - -By default, there is a single search box, which can be used to search for a given User by their `User name`, `First Name`, `Surname`, and `Email`. - -Clicking the `Show advanced filters` link, provide additional filtering options: - -- Permissions -- Role -- Only locked users - -## Exporting User Information - -From the main Users page, it is possible to export all User information into either PDF or Excel format. -This can be done by using either the `Export | Export to PDF`, or the `Export | Export to Excel` button. - -This will generate a file name similar to `Chocolatey_Users_20231122_130612.xlsx`, or `Chocolatey_Users_20231122_130612.pdf`. - -## Pre-Configured Users - -In a fresh installation of Chocolatey Central Management, there is a single pre-configured User called `ccmadmin`, which has been allocated the `CCM Admin` Role. diff --git a/input/en-us/central-management/usage/website/computers.md b/input/en-us/central-management/usage/website/computers.md deleted file mode 100644 index 48a62d5113..0000000000 --- a/input/en-us/central-management/usage/website/computers.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -Order: 40 -xref: ccm-computers -Title: Computers -Description: Information on computers within CCM -RedirectFrom: - - docs/central-management-computers - - en-us/central-management/usage/computers ---- - -Chocolatey Central Management gives you visibility into what's installed on a given computer, as well as their last check-in to Central Management and IP Address. - -The **Computers** page can be accessed from the Central Management Dashboard via the menu entry in the left-hand sidebar. - -![Computers menu entry on the CCM Dashboard](/assets/images/ccm-playwright/dashboard/left-menu-computers.png) - -## Registering a New Computer - -Client computers (agents) will show up in Central Management automatically as long as long as these conditions are met for the client computer: - -1. The `chocolatey`, `chocolatey.extension`, and `chocolatey-agent` packages are installed, alongside a valid Chocolatey for Business license. -1. The `useChocolateyCentralManagement` feature is enabled. -1. The `centralManagementServiceUrl` is set correctly in the chocolatey configuration file (typically to `https://:24020/ChocolateyManagementService`) -1. The client has access to the above URL (this may require opening the port in your firewall, etc.) so that it can resolve the SSL certificate necessary to communicate with the CCM service. - -Please see [Central Management Client Setup](xref:ccm-client) for more details and setup. - -## Viewing Installed Software on a Computer - -> :choco-info: **NOTE** -> -> Starting with Chocolatey Central Management 0.10.0, the groups that a computer is a member of is shown in both the table of all computers, as well as on the computer details pages. By default, this will only show the first 5 group memberships. If there are more group associations: -> -> - The computers table will display a `...` link in the Groups column. Upon hovering this link, a tooltip will be shown with all group memberships. -> - On the computer details page, a `View More` link will be shown. When clicked, this will cause an expansion to show all group memberships and the link will update to say `View Less`. Clicking this link again will show the default previous view. - -From the main Computers page in Central Management, locate the computer of interest in the list or by providing a search term in the table filter. -Select the :gear: **Actions** menu in the corresponding left-hand column, and click **Details**. - -![Finding a computer's details menu option](/assets/images/ccm-playwright/computers/table-row-button-action-dropdown-menu-details.png) - -You will be presented with a list of the installed software packages for the machine, similar to below. - -![Computer details screen showing installed software](/assets/images/ccm-playwright/computers/details/screen.png) - -## Creating a Draft Deployment Plan for a Computer - -Creating a Draft Deployment Plan for a Computer can be done from two pages: - -1. In the leftmost column of the Computer table you will find an :gear: **Actions** menu which will display a **Create New Deployment Plan** option. - - ![Finding the Create New Deployment Plan menu entry for a specific Computer on the Computers page](/assets/images/ccm-playwright/computers/table-row-button-action-dropdown-menu-create-new-deployment-plan.png) - -1. From the Computer Details page, click the :gear: **Actions** button and select the **Create New Deployment Plan** option. - - ![Button to create a new draft Deployment Plan from the Computer Details page](/assets/images/ccm-playwright/computers/details/button-action-dropdown-menu-create-new-deployment-plan.png) - -Clicking this option will create a New Deployment Plan. This Deployment Plan will create one Deployment Step with a [Temporary Group](#xref:ccm-groups#temporary-groups) that contains the Computer selected. Upon arriving on the Edit Deployment Plan screen, this Deployment Step will be opened and ready to add a script command. - -![Automatically created Deployment Plan showing the Deployment Step modal script command area](/assets/images/ccm-playwright/deployment-plans/edit/computers-modal-new-deployment-plan.png) - -The Deployment Plan can be saved without adding a script command, however it will be ineligible for deployment. A red warning icon will be shown on the Deployment Step, that when clicking will show a message. - -![Red popover warning on Deployment Step with ineligible deployment message](/assets/images/ccm-playwright/deployment-plans/edit/popover-ineligible-step.png) - -After adding a script command to the Deployment Step, the Deployment Plan can be deployed as outlined in the [Deployment Plans documentation](xref:ccm-deployments). - -From here, the Deployment Plan can be edited and deployed as outlined in the [Deployment Plans documentation](xref:ccm-deployments). - -## Upgrading All Outdated Software on a Computer - -Upgrading all outdated Software installed on a Computer can be done from two pages: - -1. In the leftmost column of the Computer table you will find an :gear: **Actions** menu which will display a **Upgrade Outdated Software** option. - - ![Finding the Upgrade Outdated Software menu entry for a specific Computer on the Computers page](/assets/images/ccm-playwright/computers/table-row-button-action-dropdown-menu-upgrade-outdated-software.png) - -1. From the Computer Details page, click the :gear: **Actions** button and select the **Upgrade Outdated Software** option. - - ![Button to create a new Deployment Plan to upgrade all outdated Software on a Computer from the Computer Details page](/assets/images/ccm-playwright/computers/details/button-action-dropdown-menu-upgrade-outdated-software.png) - -Clicking this option will create a New Deployment Plan. This Deployment Plan will create one Deployment Step per outdated Software. - -![Automatically created Deployment Plan showing Deployment Steps](/assets/images/ccm-playwright/deployment-plans/edit/computers-upgrade-outdated-software.png) - -Each Deployment Step has a [Temporary Group](xref:ccm-groups#temporary-groups) selected that contains the Computer, and the script command automatically entered. - -From here, the Deployment Plan can be edited and deployed as outlined in the [Deployment Plans documentation](xref:ccm-deployments). - -## Exporting a `packages.config` file for a computer - -> :choco-info: **NOTE** -> -> Starting with Chocolatey Central Management 0.11.0, the packages installed on a computer can be exported to a `packages.config` file. - -From the Computer details page, click the `Export` button and select the `Export to packages.config` option. - -![Computer details screen highlighting Export to packages.config button](/assets/images/ccm-playwright/computers/details/button-action-dropdown-menu-export-to-packages.config.png) - -## Removing a Computer from Chocolatey Central Management - -> :choco-info: **NOTE** -> -> Unless you first uninstall (at minimum) the `chocolatey-agent` or disable Central Management by disabling the feature setting, the deleted computer will reappear when the Chocolatey Agent performs its next check-in. - -From the main Computers page in Central Management, locate the computer of interest in the list or by providing a search term in the table filter. -Select the :gear: **Actions** menu in the corresponding left-hand column, and click **Delete**. You will be prompted to confirm the deletion. - -![Deleting a computer in Central Management](/assets/images/ccm-playwright/computers/table-row-button-action-dropdown-menu-delete.png) - -## FAQ - -### What do I do if computers are not showing up in CCM? - -You need to check the CCM service logs. The agent will always report success when it communicates with the service successfully. The service may reject what it receives, but due to security settings, it won't tell the client about that. - -The logs are located at `$env:ChocolateyInstall\logs\ccm-service.log`. If you are on a version of CCM prior to 0.2.0, the log will be located at `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\logs\chocolatey.service.host.log`. - -For more common errors related to checking in, see the [setup section (and component setup sub-sections)](xref:ccm-setup) as they dive deeper into common errors and resolutions related to things such as this. - -## Related Topics - -* [Chocolatey Central Management](xref:central-management) -* [Central Management - Software](xref:ccm-software) -* [Central Management - Groups](xref:ccm-groups) -* [Central Management - Reports](xref:ccm-reports) diff --git a/input/en-us/central-management/usage/website/dashboard.md b/input/en-us/central-management/usage/website/dashboard.md deleted file mode 100644 index 884ce15f38..0000000000 --- a/input/en-us/central-management/usage/website/dashboard.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -Order: 10 -xref: ccm-dashboard -Title: Dashboard -Description: Information on the dashboard page ---- - -The Dashboard page within the Chocolatey Central Management Website is the first page that can be seen after successful login. - -It captures top level information about the current state of the overall application, including: - -- Total Installed Packages - - This is the total number of packages currently installed across all the Computers that are reporting into Chocolatey Central Management. -- Total Outdated Packages - - This is the total number to outdated packages currently installed across all the Computers that are reporting into Chocolatey Central Management. -- Total Unique Installed Packages - - This is the total number of unique packages currently installed across all the Computers that are reporting into Chocolatey Central Management. -- Total Unique Outdated Packages - - This is the total number of unique outdated packages currently installed across all the Computers that are reporting into Chocolatey Central Management. - -Starting with Chocolatey Central Management 0.12.0, the following metrics are also available: - -- Total Draft/Ready Deployment Plans - - This is the total number of unique Deployment Plans in the Draft or Ready states in Chocolatey Central Management. -- Total Active Deployment Plans - - This is the total number of unique Deployment Plans in the Active state in Chocolatey Central Management. -- Total Stale Computers - - This is the total number of Computers that haven't reported into Chocolatey Central Management in the last 180 days. - -> :choco-info: **NOTE** -> -> There is a configuration value in the [Dashboard Settings](xref:ccm-administration-settings-dashboard) page to control how long a Computer has to be absent from reporting into Chocolatey Central Management before being considered stale. - -The `Last Updated` date/time that is shown is when the information was last updated by the Chocolatey Central Management Service. - -![Dashboard page for Chocolatey Central Management showing available KPI's and last updated time](/assets/images/ccm-playwright/dashboard/left-menu-dashboard.png) \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/deployments.md b/input/en-us/central-management/usage/website/deployments.md deleted file mode 100644 index b7c2dfc848..0000000000 --- a/input/en-us/central-management/usage/website/deployments.md +++ /dev/null @@ -1,485 +0,0 @@ ---- -Order: 20 -xref: ccm-deployments -Title: Deployment Plans -Description: How to deploy packages, and execute PowerShell, on client machines -RedirectFrom: - - docs/central-management-deployments - - en-us/central-management/usage/deployments ---- - -## Description - -Chocolatey Central Managements' Deployments functionality allows for pre-defined actions to be executed across any Chocolatey-managed computers. -Deployment actions can be defined as simple `choco` commands, or as fully-fledged PowerShell scripts. - -## Creating a Deployment Plan - -To setup a new Deployment Plan, you'll need to create a Deployment Plan which defines the steps for the Deployment Plan and the Computers which will run them. -In order to get started, you'll need at least the `Create New Deployment Plan` and/or the `Create New Privileged Deployment Plan` permissions applied to your user account in Chocolatey Central Management. -You will also need to have at least one Group of computers already defined. - -1. From the Chocolatey Central Management dashboard, select `Deployment Plans` from the left sidebar. - - ![Chocolatey Central Management dashboard, arrow pointing to Deployment Plans menu in the left sidebar](/assets/images/ccm-playwright/dashboard/left-menu-deployment-plans.png) - -1. Select the :heavy_plus_sign: **Create New Deployment Plan** button at the top of the page. - - ![Chocolatey Central Management Deployment Plans page, arrow pointing to Create New Deployment Plan button](/assets/images/ccm-playwright/deployment-plans/button-create-new-deployment-plan.png) - -1. (Optional) Give the Deployment Plan a custom name by clicking the edit icon displayed next to it and entering a new name. - Press **Enter** to save the new name. - - ![Chocolatey Central Management New Deployment Plan page, arrow pointing to the edit title button](/assets/images/ccm-playwright/deployment-plans/edit/button-edit-name.png) - -1. (Optional, Requires Chocolatey Central Management v0.11.0+) Add a Deployment Plan execution timeout in seconds to be used by all Deployment Steps. - - ![Chocolatey Central Management New Deployment Plan page, arrow pointing to the Deployment Plan execution timeout in seconds setting](/assets/images/ccm-playwright/deployment-plans/edit/input-execution-timeout-in-seconds.png) - - * The Deployment Plan execution timeout in seconds will be used on all steps created **after it has been modified**. A Deployment Step can override the Deployment Plan execution timeout in seconds by modifying the Deployment Step execution timeout in seconds in the Deployment Step modal located in the advanced filters dropdown. - - ![Chocolatey Central Management Deployment Step modal, arrow pointing to execution timeout in seconds](/assets/images/ccm-playwright/deployment-plans/edit/modal-step-input-execution-timeout-in-seconds.png) - -1. (Optional, Requires Chocolatey Central Management v0.4.0+) Add a schedule by selecting the :heavy_plus_sign: **Add Schedule** button. - - ![Chocolatey Central Management New Deployment Plan page, arrow pointing to Add Schedule button](/assets/images/ccm-playwright/deployment-plans/edit/button-add-schedule.png) - - * Enter a date and time, or click the :calendar: button to pick the date and time from a calendar UI. - - ![Chocolatey Central Management Deployment Plan schedule picker](/assets/images/ccm-playwright/deployment-plans/edit/calendar-start-date-time.png) - - * (Optional) If you'd like to define a maintenance window for the Deployment Plan start time, select the **Restrict schedule to a maintenance window** option and enter the ending date and time for the maintenance window. - - ![Chocolatey Central Management Deployment Plan maintenance window option](/assets/images/ccm-playwright/deployment-plans/edit/checkbox-restrict-schedule.png) - - * (Optional) If you'd like a Deployment Plan to happen again, on a recurring basis, select how often you'd like the Deployment Plan to recur. Check the [recurring Deployment Plans section for more information](#recurring-deployments) - - ![Chocolatey Central Management Deployment Plan Repeat Period](/assets/images/ccm-playwright/deployment-plans/edit/select-repeat-period.png) - -1. Select :heavy_plus_sign: **Add Step** to add your first Deployment Step. - - ![Chocolatey Central Management Deployment Plan add Deployment Step button](/assets/images/ccm-playwright/deployment-plans/edit/button-add-deployment-step.png) - -1. (Optional) In the `Create New Deployment Step` modal, enter a custom name for the Deployment Step. - - ![Chocolatey Central Management Deployment Plan new step modal](/assets/images/ccm-playwright/deployment-plans/edit/modal-step.png) - -1. Add the Deployment Step action: - * For _Basic_ Deployment Steps, select a `Script command` from the list, a `Package name` to install, and optionally a specific package version to install or whether to allow Chocolatey to install the latest prerelease package version. **NOTE:** It is not possible to use a space character within the `Package name` or `Package Version` textboxes, and the `Package Version` textbox must contain at least one digit. - - ![Chocolatey Central Management Deployment Plan basic step action](/assets/images/ccm-playwright/deployment-plans/edit/modal-step-basic-command.png) - - * For _Advanced_ Deployment Steps (requires the _Create Privileged Deployment_ user role), click the **Advanced** button and then enter one or more PowerShell script commands. - - ![Chocolatey Central Management Deployment Plan advanced step action](/assets/images/ccm-playwright/deployment-plans/edit/modal-step-advanced-command.png) - - * You can use [Sensitive Variables](xref:ccm-administration-sensitive-variables#adding-sensitive-variables-to-scripts) in an Advanced script in Chocolatey Central Management version 0.7.0 and later. - - -1. (Optional) Click **Show advanced filters** to set one or more of the following options: - * `Execution timeout`. - * `Valid exit codes`. - * `Machine contact timeout` (requires Chocolatey Central Management v0.4.0+ to edit). - * `Fail overall Deployment Plan if not successful`. - Disabling this option will allow the overall Deployment Plan to be marked as successful even if the step fails. - By default, if any Deployment Step fails, the overall Deployment Plan is marked as Failed. - * `Only run other Deployment Steps if successful`. - Enabling this option will prevent subsequent Deployment Steps from starting if this step fails. - The overall Deployment Plan will be marked as Failed, and subsequent Deployment Steps will be Cancelled. -1. Select the **Select Target Groups** tab. - - ![Chocolatey Central Management Deployment Step Select Target Group tab](/assets/images/ccm-playwright/deployment-plans/edit/modal-step-tab-select-target-groups.png) - -1. Add groups from the **Available Groups** column to the **Selected Groups** column by selecting them from the list and pressing the `>` button. You can also select the `>>` button to immediately move all groups into the **Selected Groups** column. - - ![Chocolatey Central Management Deployment Step Select Target Groups modal](/assets/images/ccm-playwright/deployment-plans/edit/modal-step-select-target-groups.png) - -1. Click the :floppy_disk: **Save** button to save the Deployment Step. - - ![Chocolatey Central Management Deployment Step Save button](/assets/images/ccm-playwright/deployment-plans/edit/modal-step-button-save.png) - -1. Continue to add steps until your Deployment Plan is complete. - -1. (Optional, requires Chocolatey Central Management v0.12.0) If you need to create multiple similar Deployment Steps, you can use the Duplicate Deployment Step button on an individual Deployment Step to make a copy of it. - - ![Chocolatey Central Management Deployment Step Duplicate button](/assets/images/ccm-playwright/deployment-plans/edit/button-duplicate-step.png) - -1. Select :floppy_disk: **Save** to save the changes to the Deployment Plan. - - - -## Recurring Deployment Plans - -As mentioned above, when creating a Deployment Plan, it is possible to select a scheduled start date/time, and in addition a Repeat Period. This Repeat Period controls how often a Deployment Plan recurs going forward. The values for the Repeat Period are: - -- `Daily` -- `Weekly` -- `Every two weeks` -- `Every four weeks` -- `Monthly` -- `Every two months` -- `Quarterly` -- `Every six months` -- `Yearly` - -Once a Deployment Plan has been assigned a Repeat Period, and it is moved to the [Ready](#ready) state, it will be shown with a slightly different icon: - -![Chocolatey Central Management Deployment Plan marked as recurring](/assets/images/ccm-playwright/deployment-plans/table-row-icon-recurring-deployment-plan.png) - -Let's take as example a Deployment Plan in the [Ready](#ready) state that is scheduled to start on `23rd August 2022 at 07:11 UTC`, with a Repeat Period of `Weekly` set. -Once this instance of the Deployment Plan moves to the [Active](#active) state, another instance of the Deployment Plan will be created. -The new instance will have the same steps and settings except for the scheduled start date/time, which will be set to exactly 1 week from the scheduled start date/time of the previous instance (in this case `30th August 2022 at 07:11 UTC`). - -For repeating Deployment Plans, a new instance of the Deployment Plan will be created once a scheduled Deployment Plan moves to the [Active](#active) state. -If a repeating Deployment Plan specifies a maintenance window date/time (`Last Scheduled Date Time`), the new instance's maintenance window will also be adjusted from the previous instance's value by the same period as the scheduled start date/time. - -> :choco-warning: **WARNING** -> -> If the scheduled start date/time of a Deployment Plan is overridden using the [Run Now](#run-now) action, the new instance of the recurring Deployment Plan will use the **scheduled** start date/time of the previous instance when calculating the next scheduled start date/time, **not** the date/time that the Deployment Plan actually started. -> If you want to change the scheduled start date/time of the recurring Deployment Plan, edit the Deployment Plan while it is in the [Ready](#ready) state to ensure that future instances of the recurring Deployment Plan will use that value when calculating the next scheduled date/time. - -While in the [Ready](#ready) state, if you use the [Cancel](#cancel) or [Delete](#delete) action on the recurring Deployment Plan, no further instances of the recurring Deployment Plan will be created. - -## Deployment Plan States - -### Draft - -A Deployment Plan is initially created in the [`Draft`](#draft) state, and will remain in this state until it is moved into the [`Ready`](#ready) state. -While it is in the [`Draft`](#draft) state, it cannot be run, and scheduled Deployment Plan start times will be ignored. - -While in the [`Draft`](#draft) state, the available actions that can be performed on a Deployment Plan are: - -- [Move To Ready](#move-to-ready) -- [Edit](#edit) -- [Duplicate](#duplicate) -- [Delete](#delete) -- [Export](#export) - -### Scheduled/Ready - -Once the Deployment Plan enters the [`Ready`](#ready) state, it's eligible to be started. -Deployment Plans in this state can be started manually or according to a schedule. - -> :choco-info: **NOTE** -> -> Any modifications to a Deployment Plan in this state will revert it back to the [`Draft`](#draft) state. - -While in the [`Ready`](#ready) state, the available actions that can be performed on a Deployment Plan are: - -- [View](#view) -- [Run Now](#run-now) -- [Edit](#edit) -- [Duplicate](#duplicate) -- [Cancel](#cancel) -- [Delete](#delete) -- [Export](#export) - -### Active - -Deployment Plans that are currently in progress will be in this state. - -While in the [`Active`](#active) state, the available actions that can be performed on a Deployment Plan are: - -- [Details](#details) -- [Duplicate](#duplicate) -- [Cancel](#cancel) -- [Export](#export) - -### Completed - -Deployment Plans that have completed running will be in either the `Success`, `Failed`, `Unreachable`, `Inconclusive`, or `Cancelled` state, depending on how the run went. - -While in one of these states, the available actions that can be performed on a Deployment Plan are: - -- [Details](#details) -- [Duplicate](#duplicate) -- [Archive](#archive) -- [Export](#export) - -In most cases Deployment Plans in one of the Completed states will remain in that same state. -However, due to changes introduced in [Chocolatey Agent v1.1.0](xref:agent-release-notes#august-22-2022), a Deployment Plan in the `Inconclusive` state due to the computer or the Agent service being shut down or restarted during the Deployment Step, may retry the task and later update the Deployment Plan's status. -This can result in the Deployment Step or overall Deployment Plan changing from the `Inconclusive` status to `Success` or `Failed` depending on the final status of the retried task. - -### Archived - -Deployment Plans that are in a [completed](#completed) state can be actioned using [`Archive`](#archive) action to hide them from the main Deployment Plans screen. -This is helpful if you'd like to reduce clutter on the main Deployment Plans screen without discarding the information the completed report contains. - -You can access archived Deployment Plans from the `Deployment Plans` page and clicking on the `View Archived Deployment Plans` button. [`Archived`](#archived) Deployment Plans will not appear in any other reports that contain Deployment Plans. - -While in the [`Archived`](#archived) state, no additional actions can be performed on a Deployment Plan. - -## Deployment Plan Actions - -Depending on the [state](#deployment-states) that a Deployment Plan is currently in, there are a defined set of actions that can be performed on them. What follows are is a description of each of those actions. - -### Move To Ready - -This action moves a Deployment Plan from the [`Draft`](#draft) state to the [`Ready`](#ready) state. While in this interim state, no additional changes can be made to the Deployment Plan. If changes are made, it will be moved back to the [`Draft`](#draft) state. - -### Edit - -The action opens the edit page for the selected Deployment Plan. Here changes can be made to the steps, schedule, groups, etc. If any changes are made on the page, a Deployment Plan that was in the [`Ready`](#ready) state, will be moved back to the [`Draft`](#draft) state. - -### Duplicate - -> :choco-info: **NOTE** -> -> This feature is available in Chocolatey Central Management starting with version 0.10.0. - -The action makes an exact copy (with the exception of any scheduled start/end time or repeat period) of any given Deployment Plan. Once the duplicate has been created, you will be taken to the edit page ready to make any additional required changes. The name of the new Deployment Plan will be the same as the original with some additional information added to the end. For example, if the original Deployment Plan was called `Install Papercut`, the name given to the duplicate would be `Install Papercut - Copy (19 Aug 2022 12:52:25)` where the timestamp is the current date time. - -> :choco-info: **NOTE** -> -> There is a specific permission to allow duplication of a Deployment Plan. If you want to configure this permission, it can be done either for an individual [user](xref:ccm-administration-users), or a specific [role](xref:ccm-administration-roles) - -### Delete - -This removes all information about the Deployment Plan from Chocolatey Central Management. - -The action cannot be undone, so care should be taken before using it. - -### View - -The action opens the edit page for the selected Deployment Plan where all the parts of the plan can be viewed. Here changes can be made to the steps, schedule, groups, etc. If any changes are made on the page, a Deployment Plan that was in the [`Ready`](#ready) state, will be moved back to the [`Draft`](#draft) state. - -### Run Now - -This action takes a Deployment Plan from the [`Ready`](#ready) state, to the [`Active`](#active) state. This can be thought of as actually setting the Deployment Plan in motion, and the steps within this Deployment Plan will begin to be picked up by the computers that are contained within the steps (in the order that has been defined). - -> :choco-warning: **WARNING** -> -> If the scheduled start date/time of a Deployment Plan is overridden using the [Run Now](#run-now) action, the new instance of the recurring Deployment Plan will use the **scheduled** start date/time of the previous instance when calculating the next scheduled start date/time, **not** the date/time that the Deployment Plan actually started. -> If you want to change the scheduled start date/time of the recurring Deployment Plan, edit the Deployment Plan while it is in the [Ready](#ready) state to ensure that future instances of the recurring Deployment Plan will use that value when calculating the next scheduled date/time. - -### Cancel - -This action stops all future steps from being performed within a Deployment Plan. Any steps that are currently active will still be allowed to complete, but no further steps will occur. - -If a recurring Deployment Plan is Cancelled from the [`Ready`](#ready) state, all future instances of the Deployment Plan are also cancelled. -If you want to skip an iteration of a recurring Deployment Plan, instead change its scheduled start time directly. - -### Details - -This action opens up the details for the selected Deployment Plans, allowing the user to see the progress so far. For example: the currently active Deployment Step, or which computers have picked up this step. This view is useful for monitoring the progress in real time, as the details pages update automatically. - -### Archive - -This action will mark any completed Deployment Plan as archived, and it will no longer be shown in the main Deployment Plans screen of Chocolatey Central Management website. You can access archived Deployment Plans from the `Deployment Plans` page and clicking on the `View Archived Deployment Plans` button. - -### Export - -This action will export the details of the Deployment Plan to a `.json` file. The name of the new Deployment Plan will be the same as the original with some additional information added to the end. For example, if the original Deployment Plan was called `Install Papercut`, the name given to the exported Deployment Plan would be `Install Papercut - Exported (19 Sept 2023 12:52:25)` where the timestamp is the current date time. - -## Deployment Plan Status Notifications - -> :choco-info: **Note** -> -> Email notifications require that the Email / SMTP settings have been configured first. -> If these settings have not been configured, email notifications will not be sent. - -### Deployment Plan Completion Notifications - -As of Chocolatey Central Management v0.11.0, all Deployment Plans will issue an email notification when they finish to the user that created the Deployment Plan. -The email notification will indicate the status of the Deployment Plan, as well as linking back to the Deployment Plan details page for further information. - -![Example email from Chocolatey Central Management for a successfully completed Deployment Plan, showing the status, start time, and finish time, as well as the Deployment Plan name and a link to the Deployment Plan details.](/assets/images/ccm-manual/deployment-plans/email-deployment-success.png) - -### Notification for Scheduled Deployment Plans Unable to Start - -As of Chocolatey Central Management v0.10.0, a scheduled Deployment Plan that fails to start will issue a push notification as well as an email notification to the user who initially created the Deployment Plan. The push notification can be viewed in Chocolatey Central Management by clicking the "bell" icon in the top navigation. - -![Example email from Chocolatey Central Management for a scheduled Deployment Plan that failed to start, showing the Deployment Plan name and scheduled start time](/assets/images/ccm-manual/deployment-plans/email-failed-scheduled-start.png) - -## FAQ - -### What Versions of Components Do I Need for Deployments to Work Properly? - -While you might be able to get things to work with Chocolatey Central Management v0.2.x and Chocolatey Agent v0.10.x, it's best to use the following: - -* Chocolatey Central Management components (`chocolatey-management-*` all 3 packages) - v0.3.0+ -* Chocolatey Agent (`chocolatey-agent` package on all clients) - v0.11.0+ -* Chocolatey Licensed Extension (`chocolatey.extension` on all clients) - v2.1.1+ - -### What Is the Chocolatey Central Management Compatibility Matrix? - -Chocolatey Central Management has specific compatibility requirements with quite a few moving parts. It is important to understand that there are some Chocolatey Agent versions that may not be able to communicate with some versions of Chocolatey Central Management and vice versa. Please see the [Chocolatey Central Management Component Compatibility Matrix](xref:central-management#ccm-component-compatibility-matrix) for details. - -### Why Do I See Some Machines Have Not Opted in for Deployments? - -If you are on the Groups screen, you may notice that some machines show up highlighted with a color. The legend below it mentions "Not Opted In For Deployments (Configuration)". - -![Group eligibility legend](/assets/images/ccm-playwright/groups/modal-warning-legend.png) - -As you can see from the text, it is meant to help you figure out the issue: - -> The Computer has not opted in, or a Group contains computers that have not opted in for Deployments by configuration. Please ensure the computer has at least chocolatey-agent v0.10.0+ installed and the feature "useChocolateyCentralManagementDeployments" has been set to enabled on the client computer. - -This is telling you that you need to ensure you set the client to allow for the use of Deployments. As it is a security consideration, it requires an explicit opt-in on client machines. See [Client Setup - Features](xref:ccm-client#features) for details on how to set it. - -### I Have Plenty of Licenses, Why Do Some Machines Show Not Opted in for Deployments and Also Exceeds Your Current License Count? - -Once you upgrade to at least Chocolatey Central Management v0.2.0, every machine will show that until they check in the next time. Once they check in, that will go away. So it's basically normal to see that until those machines check in again. - -### Can I use Chocolatey Deployment Plans to upgrade Chocolatey Central Management based components? - -You can upgrade the chocolatey-agent package via Chocolatey Central Management. To do so please see [here](xref:upgrade-agent#use-chocolatey-central-management-to-upgrade-chocolatey-agent) as this must be performed as an advanced Deployment Step. - -We do not recommend upgrading Chocolatey Central Management itself via an automated Deployment Plan process. Please see our [Chocolatey Central Management Upgrade Documentation](xref:ccm-upgrade) for the supported upgrade process. - -### What is Run Actual? - -You may have seen `--run-actual` get attached to scripts where you are running choco commands - what is it? - -This is a switch that is passed to opt out of Chocolatey Self-Service. It's typically passed by the agent service back to choco to run a command for a user. You typically would not issue this, but the agent service will, so you are likely to see it in the logs if you are looking closely. - -### What Happens if More Than One Deployment Plan is "Active" at the Same Time? - -This will depend a little bit on the version of Chocolatey Central Management you're running. -Prior to v0.4.0, control of Deployment Plans was handled entirely on a per-Deployment-_step_ basis. -This means that if you have an active Deployment Plan with some of the Computers in it idling (waiting for a later step in the Deployment Plan to begin, essentially), these machines will pick up available Deployment Steps from an unrelated Deployment Plan while they're waiting. - -As of v0.4.0 of Chocolatey Central Management, this has been fine-tuned a little bit so that any Computer which is acted on by a Deployment Step will not pick up any further Deployment Steps from unrelated Deployment Plans until all its assigned steps in the first Deployment Plan are completed. - -This can get a bit confusing, so let's consider the following scenario: - -* Deployment Plan A - * Deployment Step 1 - * Computer A - * Computer B - * Deployment Step 2 - * Computer B - * Deployment Step 3 - * Computer A -* Deployment Plan B - * Deployment Step 1 - * Computer A - -Let's say `Deployment Plan A` is started first, and `Deployment Plan B` starts while `Deployment Plan A` is in either `Deployment Step 1` or `Deployment Step 2`. -When `Deployment Plan A` reaches `Deployment Step 2`, even though `Computer A` is not currently running any Deployment Steps, it will not start running steps from `Deployment Plan B` because it still has a task to do in `Deployment Plan A`. -If you are running Chocolatey Central Management 0.3.x, `Computer A` will instead pick up and run the step from `Deployment Plan B` despite `Deployment Plan A` still being in progress. - -### Why do My Computers or Groups Show as Ineligible for Deployments While They're Opted In? - -Computers can be considered ineligible for Deployments based on two criteria: - -1. Is the computer licensed under your Chocolatey for Business license? -1. Is the computer opted in for Deployments based on the Chocolatey configuration? - -If **either** one of these two criteria is not met, that computer is considered ineligible for Deployments. - -Additionally, any group that contains any of the following will be considered ineligible: - -* An ineligible Computer -* A Group containing **any** ineligible Computers -* A Group containing **any** ineligible Groups - -### What Happens if a Computer / Group in a Deployment Becomes Ineligible? - -* For Deployment Plans that have not yet started: - * If the Deployment Plan is scheduled, it will not run until all Computers/Groups are eligible again. - * If the Deployment Plan is not scheduled, it cannot be started until all Computers/Groups are eligible again. - - Once Chocolatey Central Management has confirmed the problem Computer(s)/Group(s) are eligible again, the Deployment Plan can be started. - If the Deployment Plan was previously scheduled, and it has not passed the maintenance window time (if set), it will start at that point. -* For Deployment Plans that are currently [`Active`](#active) - * As soon as Chocolatey Central Management detects the ineligible Computer, it will terminate the current Deployment Step. - * Then, all following Deployment Steps will be `Cancelled`. - -### How Can I Run Deployment Plans in a Semi-Connected Environment? - -As of Chocolatey Central Management v0.4.0, you are able to configure Deployment Plans to tolerate semi-connected environments. -This effectively allows Chocolatey Central Management Deployments to simply wait until a machine is connected to the network before it begins a given Deployment Step. - -To configure this, you can set the `Machine Contact Timeout` value in the Advanced settings of each individual Deployment Step to `0`. -This value must be positive, or zero (which is treated as infinite). -You may want to configure this only for the first step of a Deployment Plan, or for multiple steps if you expect the target machines to be connected/disconnected over the course of the Deployment Plan. - -> :choco-info: **NOTE** -> -> If the Deployment Plan is scheduled with a maintenance window set, the `Machine Contact Timeout` value of the first Deployment Step is ignored. -> In this case, the maintenance window defines the contact timeout for the first step. -The `Execution Timeout` is the maximum allowed time for the Chocolatey Agent to execute the Deployment Step task. -Any positive value for this setting will be respected, and as with `Machine Contact Timeout`, a `0` value is treated as infinite. -However, if the execution timeout is infinite and a computer goes offline, that Deployment Step will not complete until that computer checks in again. If it errors three times attempting to provide the results, it will fail it at the client and that computer will not report results, and require manual intervention. -Infinite execution timeouts are **not recommended** for this reason — Deployment Steps may end up seemingly stalling for long periods of time and/or require manual intervention to cancel them. - -## Deployment Plans Webinars - -Catch the recording of the Jun 23rd, 2020 webinar for a full showcase of the Chocolatey Central Management Deployments features: - -https://chocolatey.org/events/chocolatey-deployments - -## Common Errors and Resolutions - -### A Deployment Step Is Stalled With Infinite Execution Timeout - -The only way to resolve this currently is to cancel the Deployment Plan itself, which can be done from the main Deployment Plans list. -On the left-hand side of the [`Active`](#active) Deployment Plans table, click the Actions menu for the corresponding Deployment Plan, and select [`Cancel`](#cancel). -You will be asked to confirm the cancellation. - -All remaining steps in the Deployment Plan will be cancelled, along with any still running or pending tasks. - -### The Updated License File Is Not Being Picked Up in the Website - -You need to restart the web executable currently. We are looking to have it automatically picked up in future releases. Here's a script to handle that: - -```powershell -Get-Service chocolatey-* | Stop-Service -Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process -Get-Service chocolatey-* | Start-Service -``` - -### A Computer or Group Is Not Showing as Available for Deployment Plans but I Have Plenty of Available Licenses - -Once you upgrade to Chocolatey Central Management v0.3.0+, you have upgraded the Agent on the machine to v0.11.0+, and it has successfully completed a check in, then that messaging should go away. Note that clients do not get a message back that there was a failure as a security feature - you'll need to consult the Chocolatey Central Management Service logs. You can find that at `$env:ChocolateyInstall\logs\ccm-service.log`, or if you are on a version of Chocolatey Central Management prior to 0.2.0, the log will be located at `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\logs\chocolatey.service.host.log`. - -### Using `choco` Commands in a Script Deployment Plan Break if Semicolons Are Used to Separate the Statements - -When constructing a PowerShell script for a Deployment Step, all Chocolatey commands must be placed on separate lines. It is not possible to do something like the following: - -
    -
  • - -
    • -
  • - -
    • -
- -::::{.tab-content .text-bg-body-secondary .p-3 .mb-3 .border-start .border-end .border-bottom .rounded-bottom} -:::{.tab-pane .fade .show .active #choco-v2 role=tabpanel aria-labelledby=choco-v2-tab} -```powershell -choco list -r; exit $LASTEXITCODE -``` - -Instead, this should be written as: - -```powershell -choco list -r -exit $LASTEXITCODE -``` -::: -:::{.tab-pane .fade #choco-v1 role=tabpanel aria-labelledby=choco-v1-tab} -```powershell -choco list --local-only -r; exit $LASTEXITCODE -``` - -Instead, this should be written as: - -```powershell -choco list --local-only -r -exit $LASTEXITCODE -``` - -::: -:::: - -For more information on when this will be addressed, you can subscribe to the [GitHub issue](https://github.com/chocolatey/chocolatey-licensed-issues/issues/158). - -## Related Topics - -* [Chocolatey Central Management](xref:central-management) -* [Chocolatey Central Management - Groups](xref:ccm-groups) -* [Chocolatey Central Management - Computers](xref:ccm-computers) -* [Chocolatey Central Management - Reports](xref:ccm-reports) diff --git a/input/en-us/central-management/usage/website/general.md b/input/en-us/central-management/usage/website/general.md deleted file mode 100644 index 5619e89e2c..0000000000 --- a/input/en-us/central-management/usage/website/general.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -Order: 70 -xref: ccm-general -Title: General -Description: Top level, general, information about Chocolatey Central Management Website functionality ---- - -## Dark/Light Mode - -> :choco-info: **NOTE** -> -> This feature is available in Chocolatey Central Management starting with version 0.10.0. - -Once signed into the Chocolatey Central Management website, you can select whether you want to use a dark or a light mode across all the web pages. This select is made using the button at the top right hand corner, as shown in the next screenshot. - -![Chocolatey Central Management dark/light mode selection](/assets/images/ccm-playwright/dashboard/dropdown-menu-theme-toggle.png) - -The selection that is made here is persisted, meaning that it will be remembered after you sign out of the Chocolatey Central Management website. - -### Dashboard in Dark Mode - -![Chocolatey Central Management dashboard using dark mode](/assets/images/ccm-playwright/dashboard/dark-mode.png) - -### Dashboard in Light Mode - -![Chocolatey Central Management dashboard using light mode](/assets/images/ccm-playwright/dashboard/light-mode.png) - -## Remembered number of table entries - -> :choco-info: **NOTE** -> -> This feature is available in Chocolatey Central Management starting with version 0.10.0. - -Across the various pages within the Chocolatey Central Management website, there are a number of different tables. Showing, for example, all the [Computers](xref:ccm-computers) that are currently reporting into Chocolatey Central Management service, or all of the [Deployment Plans](xref:ccm-deployments) that have been created. For each of these tables, it is possible to select the number of entries that you want to see in the table. The selection will be remembered between logged in sessions to the Chocolatey Central Management website (assuming you are using the same browser). - -![Drop down list showing available options for how many entries to show in a table](/assets/images/ccm-playwright/computers/dropdown-number-of-table-entries.png) - -## License Expiration Warning - -> :choco-info: **NOTE** -> -> This feature is available in Chocolatey Central Management starting with version 0.10.0. - -When your Chocolatey license is approaching its expiration date, a new banner will be shown on the [Dashboard](xref:ccm-dashboard) screen once you sign into the Chocolatey Central Management website. - -![License expiration warning shown on the Chocolatey Central Management dashboard once signed in](/assets/images/ccm-playwright/dashboard/alert-license-expiring.png) - -For a normal license, this will start showing when there are 90 days remaining on your license. - -For a trial license, this will start showing when there are 7 days remaining on your license. - -It is possible to dismiss this warning using the "x" on the far right of the banner, however, the banner will re-appear again in 2 days' time to remind you. This will repeat until the license is renewed, or until the license expires. \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/groups.md b/input/en-us/central-management/usage/website/groups.md deleted file mode 100644 index fb6c8955d4..0000000000 --- a/input/en-us/central-management/usage/website/groups.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -Order: 30 -xref: ccm-groups -Title: Groups -Description: Information on groups within Chocolatey Central Management -RedirectFrom: - - docs/central-management-groups - en-us/central-management/usage/groups ---- - -Groups are the basis on which a given [Deployment Plan](xref:ccm-deployments) operates. -A Group may contain one or more Computers, and/or other Groups. -Currently, Groups are entirely self-contained, and cannot be directly mapped from Active Directory Groups. - -The **Groups** page can be accessed from the left-hand navigation menu by selecting the **Groups** menu item. -If you do not see this menu entry, verify with your administrator whether yourhas the `View Groups` role assigned. - -![Groups menu entry on the Chocolatey Central Management Dashboard](/assets/images/ccm-playwright/dashboard/left-menu-groups.png) - -## The All Computers (Automatic Group) - -> :choco-info: **NOTE** -> -> This feature is available in Chocolatey Central Management starting with version 0.11.0. - -All Computers present in Chocolatey Central Management are automatically added to a System Managed Group named `All Computers (Automatic Group)`. This Group can not be edited or deleted. It will have a blue lock icon next to the name in the table. Hovering over this lock icon will display a tooltip with more information. - -![The All Computers (Automatic Group) on the Groups page with an arrow pointing to the Group in the table](/assets/images/ccm-playwright/groups/table-row-icon-automatic-group-lock.png) - -## Temporary Groups - -> :choco-info: **NOTE** -> -> This feature is available in Chocolatey Central Management starting with version 0.12.0. - -A Temporary Group is a Group that has been created for one or more specific circumstance, for instance as part of creating an Automatic Deployment Plan. -These Groups are normally not viewable from anywhere, other than the Deployment Plans where they are being used, and will be cleaned up on an interval when they are no longer needed. - -A Temporary Group can also not be Edited, Deleted, or Duplicated manually by a user. As well, no other Group can have such a Group as a Sub-Group. - -## Creating a Group - -On the main Groups page, select the **+ Create New Group** button. - -![Create New Group button on the Groups page](/assets/images/ccm-playwright/groups/button-create-new-group.png) - -Fill in a Name for the Group and (optionally) a Description in the appropriate fields in the _Create New Group_ modal. -Then, select the Computer(s) or existing Group(s) you would like to include in the new Group and click the **>** button in the _Available Groups/Computers_ column to add the selected items, or click the **>>** button to add all available Groups and Computers into the new Group. - -![New Group Modal](/assets/images/ccm-playwright/groups/modal-create-new-group.png) - -Click :floppy_disk: **Save** to close the modal and create the new Group. - -## Editing a Group - -> :choco-info: **NOTE** -> -> If you do not see the **Edit** menu entry or the :gear: **Actions** buttons, consult your administrator to determine if you have the Edit Groups role assigned. - -On the main Groups page, find the Group you want to edit. -You can enter a search term in the text field to filter results by typing in part of their Name or Description and clicking the :mag: button. -Select the :gear: **Actions** button on the left-hand side of the Group, and then select **Edit** to open the _Edit Group_ modal. - -![Edit menu entry in Group actions flyout menu](/assets/images/ccm-playwright/groups/table-row-button-action-dropdown-menu-edit.png) - -From the **Edit Group** modal, you can modify the Group name and description, and modify members by adding or removing Groups and/or Computers. - -## Deleting a Group - -> :choco-info: **NOTE** -> -> If you do not see the **Delete** menu entry or the :gear: **Actions** buttons, consult your administrator to determine if you have the appropriate role assigned to your account. - -On the main Groups page, find the Group you want to edit. -You can enter a search term in the text field to filter results by typing in part of their Name or Description and clicking the :mag: button. -Similar to the [Edit Group](#editing-a-group) action, select the :gear: **Actions** button on the left-hand side of the Group, and instead select **Delete**. -You will be prompted to confirm the deletion. - -## Duplicating a Group - -> :choco-info: **NOTE** -> -> If you do not see the **Duplicate** menu entry or the :gear: **Actions** buttons, consult your administrator to determine if you have the appropriate role assigned to your account. - -On the main Groups page, find the Group you want to duplicate. -You can enter a search term in the text field to filter results by typing in part of their Name or Description and clicking the :mag: button. -Similar to the [Edit Group](#editing-a-group) action, select the :gear: **Actions** button on the left-hand side of the Group, and instead select **Duplicate**. -If the Group being duplicated is a system managed Group, a confirmation message will be shown indicating that the duplicated Group will not be system managed. -A success message will be shown that mentions that the Group was duplicated, and if you have permissions to Edit a Group a dialog to edit this duplicated Group will be shown. - -## Viewing a Group's Details - -On the main Groups page, find the group you want to view. -You can enter a search term in the text field to filter results by typing in part of their Name or Description and clicking the :mag: button. -Select the :gear: **Actions** button on the left-hand side of the group, and select **Details**. - -![Details menu entry in Group actions flyout menu](/assets/images/ccm-playwright/groups/table-row-button-action-dropdown-menu-details.png) - -On the Group Details page, you'll find a searchable list of all Computers and Groups that are in the Group, as well as a more detailed view of the Group information. - -![Group Details screen showing the Computers and Groups that are currently in the Group](/assets/images/ccm-playwright/groups/details/screen.png) - -## Creating a Deployment Plan from a Group - -Creating a Deployment Plan for a Group can be done from two pages: - -1. In the leftmost column of the Groups table you will find an :gear: **Actions** menu which will display a **Create New Deployment Plan** option. - - ![Finding the Create New Deployment Plan menu entry for a specific Group on the Groups page](/assets/images/ccm-playwright/groups/table-row-button-action-dropdown-menu-create-new-deployment-plan.png) - -1. From the Group Details page, click the :gear: **Actions** button and select the **Create New Deployment Plan** option. - - ![Button to create a new Draft Deployment Plan for a Group from the Group Details page](/assets/images/ccm-playwright/groups/details/button-action-dropdown-menu-create-new-deployment-plan.png) - -Clicking this option will create a New Deployment Plan. This Deployment Plan will create one Deployment Step with the chosen Target Group selected. Upon arriving on the Edit Deployment Plan screen, this Deployment Step will be opened and ready to add a script command. - -![Automatically created Deployment Plan showing the Deployment Step modal script command area](/assets/images/ccm-playwright/deployment-plans/edit/groups-modal-new-deployment-plan.png) - -The Deployment Plan can be saved without adding a script command, however it will be ineligible for deployment. A red warning icon will be shown on the Deployment Step, that when clicking will show a message. - -![Red popover warning on Deployment Step with ineligible deployment message](/assets/images/ccm-playwright/deployment-plans/edit/popover-ineligible-step.png) - -After adding a script command to the Deployment Step, the Deployment Plan can be deployed as outlined in the [Deployment Plans documentation](xref:ccm-deployments). - -## Eligibility for Deployments - -The Create / Edit Group modals display Groups or Computers that are ineligible for Deployment Steps in either red or orange, depending on the reason for their ineligibility. -**All** Groups and Computers in a given Group must have their eligibility clear in order for that Group to be used as part of a Deployment Step. -If a Deployment Step is targeting ineligible Groups, the Deployment Plan cannot be started until the eligibility status(es) of the affected Computers has been resolved. - -![Group eligibility legend](/assets/images/ccm-playwright/groups/modal-warning-legend.png) - -## FAQ - -### Why do I see some machines have not opted in for Deployments? - -If you are on the Groups screen, you may notice that some machines show up highlighted with a coloring, and one of those colorings is an orange - the legend below it mentions "Not Opted In For Deployments (Configuration)". - -![Group eligibility legend](/assets/images/ccm-playwright/groups/modal-warning-legend.png) - -As you can see from the text, it is meant to help you figure out the issue: - -> The Computer has not opted in, or a Group contains Computers that have not opted in, for deployments by configuration. Please ensure the Computer has at least Chocolatey Agent v0.10.0+ installed and the feature `useChocolateyCentralManagementDeployments` has been set to enabled on the client Computer. - -This is telling you that you need to ensure you set the client to allow for the use of Deployments. As it is a security consideration, it requires an explicit opt-in on client machines. See [Client Setup - Features](xref:ccm-client#features) for details on how to set it. - -### I have plenty of licenses, why do some machines show not opted in for deployments and also exceeds your current license count? - -Once you upgrade to at least CCM v0.2.0, every machine will show that until they check in the next time. Once they check in, that will go away. So it's basically normal to see that until those machines check in again. - -## Common Errors and Resolutions - -### A Computer or Group is not showing as available for deployments, but I have plenty of available licenses - -Once you upgrade to Central Management v0.3.0+, you have upgraded the Agent on the machine to v0.11.0+, and it has successfully completed a check in, then that messaging should go away. Note that clients do not get a message back that there was a failure as a security feature - you'll need to consult the Central Management Service logs. You can find that at `$env:ChocolateyInstall\logs\ccm-service.log`, or if you are on a version of CCM prior to 0.2.0, the log will be located at `$env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\logs\chocolatey.service.host.log`. - -## Related Topics - -* [Chocolatey Central Management](xref:central-management) -* [Central Management - Deployments](xref:ccm-deployments) -* [Central Management - Computers](xref:ccm-computers) diff --git a/input/en-us/central-management/usage/website/index.md b/input/en-us/central-management/usage/website/index.md deleted file mode 100644 index 5884ed18ca..0000000000 --- a/input/en-us/central-management/usage/website/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 10 -xref: ccm-usage-website -Title: Website -Description: Information about how to work with the different entities/functionality contained within the Chocolatey Central Management Website ---- \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/reports.md b/input/en-us/central-management/usage/website/reports.md deleted file mode 100644 index 00bed41418..0000000000 --- a/input/en-us/central-management/usage/website/reports.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -Order: 60 -xref: ccm-reports -Title: Reports -Description: Information on reports within Chocolatey Central Management -RedirectFrom: - - docs/central-management-reports - - en-us/central-management/usage/reports ---- - -Chocolatey Central Management Reports section currently allows for the following reports to be generated: - -- [Outdated Software](#outdated-software) -- [Deployment Plans](#deployment-plans) - -## Outdated Software - -Outdated Software Reports can be generated at any time, as long as there is at least one known Outdated Software package. -If there is no Outdated Software, a report cannot be generated. - -When generating an Outdated Software Report, a snapshot of the current Outdated Software will be captured for the report. -Generated reports will be displayed in a list, showing the date and time they were created. - -Reports can be exported from this screen via the :gear: **Actions** menu, and selecting the desired export type. - -![Outdated Reports export to Excel](/assets/images/ccm-playwright/reports/outdated-software/table-row-button-action-dropdown-menu-export-to-excel.png) - -![Outdated Reports export to PDF](/assets/images/ccm-playwright/reports/outdated-software/table-row-button-action-dropdown-menu-export-to-pdf.png) - -When clicking on the date and time for a report, or selecting the :gear: **Actions** menu and then **Details**, the Outdated Software Details screen will be shown. -The report will display the name and version of any Outdated Software, along with any Computers that each Outdated Software is installed on. - -![Outdated Software Details view](/assets/images/ccm-playwright/reports/outdated-software/details/screen.png) - -The Outdated Software Report currently being viewed can be exported from this screen via the **Export** menu at the top-right. - -![Outdated Software Details view, showing the Export button options](/assets/images/ccm-playwright/reports/outdated-software/details/button-export.png) - -## Deployment Plans - -The Deployment Plans Report displays all completed Deployment Plans. It allows you to search for a subset of Deployment Plans or adjust the sorting order, or filter the displayed reports by their final Status. - -![Deployment Plans report page](/assets/images/ccm-playwright/reports/deployment-plans/screen.png) - -Clicking the name of an individual Deployment Plan will take you to the Deployment Plan Details screen, similar to those shown on the main [Deployment Plans](xref:ccm-deployments) page. \ No newline at end of file diff --git a/input/en-us/central-management/usage/website/software.md b/input/en-us/central-management/usage/website/software.md deleted file mode 100644 index eb5866dd91..0000000000 --- a/input/en-us/central-management/usage/website/software.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -Order: 50 -xref: ccm-software -Title: Software -Description: Information on software within CCM -RedirectFrom: - - docs/central-management-software - - en-us/central-management/usage/software ---- - -Chocolatey Central Management gives you direct visibility into the software packages in use in your organization, making it easy to see which machines are out of date and may need packages updated. -Software packages can be viewed in the context of the organization as a whole, or in the context of an individual computer. - -The main **Software** page can be accessed from the Central Management dashboard via the menu entry in the left-hand sidebar. - -![Software menu entry on the CCM dashboard](/assets/images/ccm-playwright/dashboard/left-menu-software.png) - -## Main Page - -The Software main page lists all installed software in any computers that have checked in to Central Management, including version information and whether the package is outdated (has a newer version available). - -![Software main page](/assets/images/ccm-playwright/software/screen.png) - -## Upgrade Individual Software - -In the leftmost column of the Software table you will find an :gear: **Actions** menu which will display an **Upgrade** option on outdated Software. - -![Finding the Upgrade menu entry for a specific Software entry](/assets/images/ccm-playwright/software/table-row-button-action-dropdown-menu-upgrade.png) - -Clicking this option will create a New Deployment Plan. This Deployment Plan will create one Deployment Step with a [Temporary Group](xref:ccm-groups#temporary-groups) that contains all the Computers the outdated Software is currently installed on. - -From here, the Deployment Plan can be edited and deployed as outlined in the [Deployment Plans documentation](xref:ccm-deployments). - -## Uninstall Individual Software - -In the leftmost column of the Software table you will find an :gear: **Actions** menu which will display an **Uninstall** option. - -![Finding the Upgrade menu entry for a specific Software entry](/assets/images/ccm-playwright/software/table-row-button-action-dropdown-menu-uninstall.png) - -Clicking this option will create a New Deployment Plan. This Deployment Plan will create one Deployment Step with a [Temporary Group](xref:ccm-groups#temporary-groups) that contains all the Computers the Software is currently installed on. - -From here, the Deployment Plan can be edited and deployed as outlined in the [Deployment Plans documentation](xref:ccm-deployments). - -## Upgrade All Software - -From the Software main page, click the **Create New Deployment Plan** button and select the **Upgrade Outdated Software** option. - -![Button to upgrade all outdated Software from the Software main page](/assets/images/ccm-playwright/software/button-action-dropdown-menu-upgrade-outdated-software.png) - -Clicking this option will create a New Deployment Plan. This Deployment Plan will contain one Deployment Step per outdated piece of Software. - -![Automatically created Deployment Plan showing a Deployment Step for each piece of Software](/assets/images/ccm-playwright/deployment-plans/edit/software-upgrade-outdated-software.png) - -Each Deployment Step will create a [Temporary Group](xref:ccm-groups#temporary-groups) that contains all the Computers the Software is currently installed on. - -From here, the Deployment Plan can be edited and deployed as outlined in the [Deployment Plan documentation](xref:ccm-deployments). - -## Software Details - -In the leftmost column of the Software table you will find an :gear: **Actions** menu which will display a **Details** option. -Clicking this option will take you to the **Software Details** page. - -![Finding the Details menu entry for a specific Software entry](/assets/images/ccm-playwright/software/table-row-button-action-dropdown-menu-details.png) - -On the _Software Details_ page, you'll find a searchable list of all computers that currently have the package installed, as well as a more verbose view of the package information. - -![Software Details page](/assets/images/ccm-playwright/software/details/screen.png) - -### Upgrade Individual Software - -From the Software Details page of an outdated Software, click the **Actions** button and select the **Upgrade Software** option. - -![Button to upgrade individual Software on a Computer from the Software Details page](/assets/images/ccm-playwright/software/details/button-action-dropdown-menu-upgrade-software.png) - -Clicking this option will create a New Deployment Plan. This Deployment Plan will create one Deployment Step with a [Temporary Group](xref:ccm-groups#temporary-groups) that contains all the Computers the Software is currently installed on. - -From here, the Deployment Plan can be edited and deployed as outlined in the [Deployment Plan documentation](xref:ccm-deployments). - -### Uninstall Individual Software - -From the Software Details page, click the **Actions** button and select the **Uninstall Software** option. - -![Button to uninstall individual outdated Software on a Computer from the Software Details page](/assets/images/ccm-playwright/software/details/button-action-dropdown-menu-uninstall-software.png) - -Clicking this option will create a New Deployment Plan. This Deployment Plan will create one Deployment Step with a [Temporary Group](xref:ccm-groups#temporary-groups) that contains all the Computers the Software is currently installed on. - -From here, the Deployment Plan can be edited and deployed as outlined in the [Deployment Plan documentation](xref:ccm-deployments). - -## Related Topics - -* [Central Management - Computers](xref:ccm-computers) -* [Central Management - Reports](xref:ccm-reports) - -[Chocolatey Central Management](xref:central-management) diff --git a/input/en-us/choco/commands/cache.md b/input/en-us/choco/commands/cache.md deleted file mode 100644 index ba98401766..0000000000 --- a/input/en-us/choco/commands/cache.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -Order: 5 -xref: choco-command-cache -Title: Cache -Description: Cache Command (choco cache) -RedirectFrom: - - docs/commandscache - - docs/commands-cache ---- - - - -# Cache Command (choco cache) - -> :choco-warning: **WARNING** -> -> This command was introduced in Chocolatey CLI v2.1.0 - -Get the statistics of what Chocolatey CLI has cached or clear any cached -items in the current context. - -The behavior of this command will vary depending on whether it is running in an elevated context or not. -Statistics and removing cached items will always happen on the User HTTP Cache. -However, the System HTTP Cache will only be considered if running in an elevated context. - -## Usage - - choco cache [list]|remove [options/switches] - -## Examples - - choco cache - choco cache list - choco cache remove - choco cache remove --expired - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - --expired - Expired - Remove cached items that have expired. - -~~~ - -[Command Reference](xref:choco-commands) - - -*> :choco-info: **NOTE*** This documentation has been automatically generated from `choco cache -h`. - diff --git a/input/en-us/choco/commands/config.md b/input/en-us/choco/commands/config.md deleted file mode 100644 index 211195233c..0000000000 --- a/input/en-us/choco/commands/config.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -Order: 10 -xref: choco-command-config -Title: Config -Description: Config Command (choco config) -RedirectFrom: - - docs/commandsconfig - - docs/commands-config ---- - - - -# Config Command (choco config) - -Chocolatey will allow you to interact with the configuration file settings. - -## Usage - - choco config [list]|get|set|unset [] - -## Examples - - choco config - choco config list - choco config get cacheLocation - choco config get --name cacheLocation - choco config set cacheLocation c:\temp\choco - choco config set --name cacheLocation --value c:\temp\choco - choco config unset proxy - choco config unset --name proxy - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: nothing to do, config already set/unset (enhanced) - -> :choco-info: **NOTE** -> -> Starting in v2.3.0, if you have the feature 'useEnhancedExitCodes' - turned on, then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## See It In Action - -![Config shown in action](/assets/images/gifs/choco_config.gif) - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - --name=VALUE - Name - the name of the config setting. Required with some actions. - Defaults to empty. - - --value=VALUE - Value - the value of the config setting. Required with some actions. - Defaults to empty. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco config -h`. - diff --git a/input/en-us/choco/commands/download.md b/input/en-us/choco/commands/download.md deleted file mode 100644 index 575a8b52c6..0000000000 --- a/input/en-us/choco/commands/download.md +++ /dev/null @@ -1,303 +0,0 @@ ---- -Order: 20 -xref: choco-command-download -Title: Download -Description: Download Command (choco download) -RedirectFrom: - - docs/commandsdownload - - docs/commands-download ---- - - - -# Download Command (choco download) - -### Package Copy / Package Downloader - -Chocolatey [Licensed Editions](https://chocolatey.org/compare) only. - -Downloads a package from a source and unpacks it. - -### Package Internalizer - -[Chocolatey for Business](https://chocolatey.org/compare) (C4B) and Managed Service Providers (MSP) only. - -Downloads a package from a source, optionally downloading remote - resources and recompiling the package to use internal resources. This - takes an existing package and makes it available without any internet - requirement. - -See https://docs.chocolatey.org/en-us/features/package-internalizer - - -## Usage - - choco download [] [install_script_variable=value] - - Install script variables are values that are discovered in the - chocolateyInstall.ps1 (or a script it calls). When you find values - there maybe don't get found and replaced or they use a default - value and you want to provide a value for them to use instead, you - can find them and then provide the value you want to pass instead. - For example, in the Firefox package, it uses a default value of - 'en-US' for `$locale`. If you want to change that, you can add - `locale` and a value, which will replace `$locale` in the script, - e.g. `choco download firefox --internalize locale=en-GB`. - -## Examples - - choco download sysinternals - - #### [Chocolatey for Business](https://chocolatey.org/compare) / Chocolatey for MSP - choco download notepadplusplus --internalize - choco download notepadplusplus.install --internalize --resources-location \\server\share - choco download notepadplusplus.install --internalize --resources-location http://somewhere/internal --append-useoriginallocation - choco download KB3033929 --internalize -internalize-all-urls --append-useoriginallocation - choco download firefox --internalize locale=es-AR - - -## See It In Action - -Coming soon - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -s, --source=VALUE - Source - The source to find the package(s) to download. Defaults to - default feeds. - - --version=VALUE - Version - A specific version to download. Defaults to unspecified. - - --pre, --prerelease - Prerelease - Include Prereleases? Defaults to false. - - -u, --user=VALUE - User - used with authenticated feeds. Defaults to empty. - - -p, --password=VALUE - Password - the user's password to the source. Defaults to empty. - - --cert=VALUE - Client certificate - PFX pathname for an x509 authenticated feeds. - Defaults to empty. - - --cp, --certpassword=VALUE - Certificate Password - the client certificate's password to the source. - Defaults to empty. - - --out, --outdir, --outputdirectory, --output-directory=VALUE - OutputDirectory - Specifies the directory for the downloaded Chocolatey - package file. If not specified, uses the current directory. - - -i, --ignoredependencies, --ignore-dependencies - IgnoreDependencies - Ignore dependencies when installing package(s). - Licensed editions only. Defaults to false. - - --installed, --installed-packages - Installed Packages - Download all installed Chocolatey packages. - Licensed editions only. Defaults to false. - - --ignore-unfound, --ignore-unfound-packages - Ignore Unfound Packages - When downloading more than one package, - continue when one is unfound. Licensed editions only. Defaults to false. - - --disable-repository-optimizations, --disable-package-repository-optimizations - Disable Package Repository Optimizations - Do not use optimizations for - reducing bandwidth with repository queries during package - install/upgrade/outdated operations. Should not generally be used, - unless a repository needs to support older methods of query. When used, - this makes queries similar to the way they were done in earlier versions - of Chocolatey. Overrides the default feature - 'usePackageRepositoryOptimizations' set to 'True'. - - --recompile, --internalize - Recompile / Internalize - Download all external resources and recompile - the package to use the local resources instead. Business editions only. - - --resources-location=VALUE - Resources Location - When internalizing, use this location for resources - instead of embedding the downloaded resources into the package. Can be a - file share or an internal url location. When it is a file share, it will - attempt to download to that location. When it is an internal url, it - will download locally and give further instructions on where it should - be uploaded to match package edits. Business editions only. - - --download-location=VALUE - Download Location - OPTIONAL - When internalizing, download the - resources to this location. Used with Resources Location (and defaults - to Resources Location when not set). Business editions only. - - -a, --all-urls, --internalize-all, --internalize-all-urls - All Urls - OPTIONAL - When internalizing, Chocolatey would normally only - internalize packages with known helpers. Add this switch to make it - download anytime a URL is found. Business editions only. - - --append-useoriginallocation, --append-use-original-location - Append -UseOriginalLocation - When `Install-ChocolateyPackage` is - internalized, append the `-UseOriginalLocation` parameter to the - function. Business editions only. Overrides the feature - 'internalizeAppendUseOriginalLocation' set to by default to 'True'. - - --sdc, --skipdownloadcache, --skip-download-cache - Skip Download Cache - Use the original download url even if a private - CDN cache is available for a package. Overrides the default feature - 'downloadCache' set to 'True'. Business editions only. - See https://docs.chocolatey.org/en-us/features/private-cdn - - --dc, --downloadcache, --download-cache, --use-download-cache - Use Download Cache - Use private CDN cache if available for a package. - Overrides the default feature 'downloadCache' set to 'True'. Business - editions only. - See https://docs.chocolatey.org/en-us/features/private-cdn - - --svc, --skipvirus, --skip-virus, --skipviruscheck, --skip-virus-check - Skip Virus Check - Skip the virus check for downloaded files on this ru- - n. Overrides the default feature 'virusCheck' set to 'False'. Licensed - editions only. - See https://docs.chocolatey.org/en-us/features/virus-check - - --virus, --viruscheck, --virus-check - Virus Check - check downloaded files for viruses. Overrides the default - feature 'virusCheck' set to 'False'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/virus-check - - --viruspositivesmin, --virus-positives-minimum=VALUE - Virus Check Minimum Scan Result Positives - the minimum number of scan - result positives required to flag a package. Used when virusScannerType - is VirusTotal. Overrides the default configuration value - 'virusCheckMinimumPositives' set to '4'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/virus-check - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco download -h`. - diff --git a/input/en-us/choco/commands/export.md b/input/en-us/choco/commands/export.md deleted file mode 100644 index 7039874fb2..0000000000 --- a/input/en-us/choco/commands/export.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -Order: 30 -xref: choco-command-export -Title: Export -Description: Export Command (choco export) -RedirectFrom: - - docs/commandsexport - - docs/commands-export ---- - - - -# Export Command (choco export) - -Export all currently installed packages to a file. - -This is especially helpful when re-building a machine that was created -using Chocolatey. Export all packages to a file, and then re-install -those packages onto new machine using `choco install packages.config`. - -## Usage - - choco export [] - -## Examples - - choco export - choco export --include-version-numbers - choco export "'c:\temp\packages.config'" - choco export "'c:\temp\packages.config'" --include-version-numbers - choco export -o="'c:\temp\packages.config'" - choco export -o="'c:\temp\packages.config'" --include-version-numbers - choco export --output-file-path="'c:\temp\packages.config'" - choco export --output-file-path="'c:\temp\packages.config'" --include-version-numbers - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -o, --output-file-path=VALUE - Output File Path - the path to where the list of currently installed - packages should be saved. Defaults to packages.config. - - --include-version-numbers, --include-version - Include Version Numbers - controls whether or not version numbers for - each package appear in generated file. Defaults to false. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco export -h`. - diff --git a/input/en-us/choco/commands/feature.md b/input/en-us/choco/commands/feature.md deleted file mode 100644 index 029801c4a0..0000000000 --- a/input/en-us/choco/commands/feature.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -Order: 40 -xref: choco-command-feature -Title: Feature -Description: Feature Command (choco feature) -RedirectFrom: - - docs/commandsfeature - - docs/commands-feature ---- - - - -# Feature Command (choco feature) - -Chocolatey will allow you to interact with features. - -## Usage - - choco feature [list]|disable|enable [] - -## Examples - - choco feature - choco feature list - choco feature get checksumFiles - choco feature get --name=checksumFiles - choco feature disable --name=checksumFiles - choco feature enable --name=checksumFiles - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: nothing to do, feature already set (enhanced) - -> :choco-info: **NOTE** -> -> Starting in v2.3.0, if you have the feature 'useEnhancedExitCodes' - turned on, then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -n, --name=VALUE - Name - the name of the source. Required with actions other than list. - Defaults to empty. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco feature -h`. - diff --git a/input/en-us/choco/commands/features.md b/input/en-us/choco/commands/features.md deleted file mode 100644 index 5745f2cb51..0000000000 --- a/input/en-us/choco/commands/features.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -Order: 45 -xref: choco-command-features -Title: Features -Description: Features Command (choco features) -RedirectFrom: - - docs/commandsfeatures - - docs/commands-features -ShowInNavbar: false -ShowInSidebar: false ---- - - - -# Feature Command (choco features) - -Chocolatey will allow you to interact with features. - -## Usage - - choco feature [list]|disable|enable [] - -## Examples - - choco feature - choco feature list - choco feature get checksumFiles - choco feature get --name=checksumFiles - choco feature disable --name=checksumFiles - choco feature enable --name=checksumFiles - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: nothing to do, feature already set (enhanced) - -> :choco-info: **NOTE** -> -> Starting in v2.3.0, if you have the feature 'useEnhancedExitCodes' - turned on, then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -n, --name=VALUE - Name - the name of the source. Required with actions other than list. - Defaults to empty. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco features -h`. - diff --git a/input/en-us/choco/commands/find.md b/input/en-us/choco/commands/find.md deleted file mode 100644 index b76d46767e..0000000000 --- a/input/en-us/choco/commands/find.md +++ /dev/null @@ -1,289 +0,0 @@ ---- -Order: 35 -xref: choco-command-find -Title: Find -Description: Find Command (choco find) -RedirectFrom: - - docs/commandsfind - - docs/commands-find ---- - - - -# Search Command (choco find) - -Chocolatey will perform a search for a package local or remote. - -## Usage - - choco find [] - choco search [] - -## Examples - - choco search git - choco search git --source="'https://somewhere/out/there'" - choco search bob -s "'https://somewhere/protected'" -u user -p pass - choco search --page=0 --page-size=25 - choco search 7zip --all-versions --exact - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -Enhanced: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: no results (enhanced) - -> :choco-info: **NOTE** -> -> If you have the feature 'useEnhancedExitCodes' turned on, - then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## See It In Action - -![choco find](/assets/images/gifs/choco_search.gif) - - -## Alternative Sources -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -s, --source=VALUE - Source - Source location for install. Can use special 'windowsfeatures', - 'ruby', 'cygwin', or 'python' sources. Defaults to sources. - - --idonly, --id-only - Id Only - Only return Package Ids in the list results. - - --pre, --prerelease - Prerelease - Include Prereleases? Defaults to false. - - -i, --includeprograms, --include-programs - IncludePrograms - Filters out apps Chocolatey has listed as packages and - includes those in the list. Defaults to false. - - -a, --all, --allversions, --all-versions - AllVersions - include results from all versions. - - --version=VALUE - Version - Specific version of a package to return. - - -u, --user=VALUE - User - used with authenticated feeds. Defaults to empty. - - -p, --password=VALUE - Password - the user's password to the source. Defaults to empty. - - --cert=VALUE - Client certificate - PFX pathname for an x509 authenticated feeds. - Defaults to empty. - - --cp, --certpassword=VALUE - Certificate Password - the client certificate's password to the source. - Defaults to empty. - - --page=VALUE - Page - the 'page' of results to return. Defaults to return all results. - - --page-size=VALUE - Page Size - the amount of packages to return in each page of results. - NOTE: this value is per source. Defaults to 25 for each source that is - included in query. - - -e, --exact - Exact - Only return packages with this exact name. - - --by-id-only - ByIdOnly - Only return packages where the id contains the search filter. - - --by-tag-only, --by-tags-only - ByTagOnly - Only return packages where the search filter matches on the - tags. - - --id-starts-with - IdStartsWith - Only return packages where the id starts with the search - filter. - - --order-by-popularity - OrderByPopularity - Sort by package results by popularity. - - --approved-only - ApprovedOnly - Only return approved packages - this option will filter - out results not from the [community repository](https://community.chocolatey.org/packages). - - --download-cache, --download-cache-only - DownloadCacheAvailable - Only return packages that have a download cache - available - this option will filter out results not from the community - repository. - - --not-broken - NotBroken - Only return packages that are not failing testing - this - option only filters out failing results from the [community feed](https://community.chocolatey.org/packages). It will - not filter against other sources. - - --detail, --detailed - Detailed - Alias for verbose. - - --disable-repository-optimizations, --disable-package-repository-optimizations - Disable Package Repository Optimizations - Do not use optimizations for - reducing bandwidth with repository queries during package - install/upgrade/outdated operations. Should not generally be used, - unless a repository needs to support older methods of query. When - disabled, this makes queries similar to the way they were done in - earlier versions of Chocolatey. Overrides the default feature - 'usePackageRepositoryOptimizations' set to 'True'. - - --include-configured-sources - Include Configured Sources - When using the '--source' option, this - appends the sources that have been saved into the chocolatey.config file - by 'source' command. Available in 2.3.0+ - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco find -h`. - diff --git a/input/en-us/choco/commands/help.md b/input/en-us/choco/commands/help.md deleted file mode 100644 index 4d94ae453a..0000000000 --- a/input/en-us/choco/commands/help.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -Order: 50 -xref: choco-command-help -Title: Help -Description: Help Command (choco help) -RedirectFrom: - - docs/commandshelp - - docs/commands-help ---- - - - -# Help Command (choco help) - -Displays the complete help information, including: - -* Available commands -* How to pass options/switches -* Scripting best practices and style guide - -## Usage - - choco help - -## Examples - - choco help - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - -[Command Reference](xref:choco-commands) \ No newline at end of file diff --git a/input/en-us/choco/commands/index.md b/input/en-us/choco/commands/index.md deleted file mode 100644 index 7c3b4f822c..0000000000 --- a/input/en-us/choco/commands/index.md +++ /dev/null @@ -1,333 +0,0 @@ ---- -Order: 40 -xref: choco-commands -Title: Commands -Description: Full list of all available Chocolatey commands -RedirectFrom: - - docs/commandsreference - - docs/commands-reference ---- - -# Command Reference - - - -This is a listing of all of the different things you can pass to choco. - - - -## Commands - - * [apikey](xref:choco-command-apikey) - retrieves, saves or deletes an API key for a particular source - * [cache](xref:choco-command-cache) - Manage the local HTTP caches used to store queries (v2.1.0+) - * [config](xref:choco-command-config) - Retrieve and configure config file settings - * [convert](xref:choco-command-convert) - converts packages from one type to another type - * [download](xref:choco-command-download) - downloads packages - optionally internalizing all remote resources - * [export](xref:choco-command-export) - exports list of currently installed packages - * [feature](xref:choco-command-feature) - view and configure choco features - * [features](xref:choco-command-features) - view and configure choco features (alias for feature) - * [find](xref:choco-command-find) - searches remote packages (alias for search) - * [help](xref:choco-command-help) - displays top level help information for choco - * [info](xref:choco-command-info) - retrieves package information. Shorthand for choco search pkgname --exact --verbose - * [install](xref:choco-command-install) - installs packages using configured sources - * [list](xref:choco-command-list) - lists local packages - * [new](xref:choco-command-new) - creates template files for creating a new Chocolatey package - * [optimize](xref:choco-command-optimize) - optimizes installation, reducing space usage - * [outdated](xref:choco-command-outdated) - retrieves packages that are outdated. Similar to upgrade all --noop - * [pack](xref:choco-command-pack) - packages nuspec, scripts, and other Chocolatey package resources into a nupkg file - * [pin](xref:choco-command-pin) - suppress upgrades for a package - * [push](xref:choco-command-push) - pushes a compiled nupkg to a source - * [rule](xref:choco-command-rule) - view or list implemented package rules (v2.3.0+) - * [search](xref:choco-command-search) - searches remote packages - * [setapikey](xref:choco-command-setapikey) - retrieves, saves or deletes an API key for a particular source (alias for apikey) - * [source](xref:choco-command-source) - view and configure default sources - * [sources](xref:choco-command-sources) - view and configure default sources (alias for source) - * [support](xref:choco-command-support) - provides support information - * [sync](xref:choco-command-sync) - synchronizes against system installed software - generates missing packages - * [synchronize](xref:choco-command-synchronize) - synchronizes against system installed software - generates missing packages - * [template](xref:choco-command-template) - get information about installed templates - * [templates](xref:choco-command-templates) - get information about installed templates (alias for template) - * [uninstall](xref:choco-command-uninstall) - uninstalls a package - * [unpackself](xref:choco-command-unpackself) - [DEPRECATED] will be removed in v3.0.0 - re-installs Chocolatey base files - * [upgrade](xref:choco-command-upgrade) - upgrades packages from various sources - - -Please run chocolatey with `choco command -help` for specific help on - each command. - -## How To Pass Options / Switches - -You can pass options and switches in the following ways: - - * Unless stated otherwise, an option/switch should only be passed one - time. Otherwise you may find weird/non-supported behavior. - * `-`, `/`, or `--` (one character switches should not use `--`) - * **Option Bundling / Bundled Options**: One character switches can be - bundled. e.g. `-d` (debug), `-f` (force), `-v` (verbose), and `-y` - (confirm yes) can be bundled as `-dfvy`. - * NOTE: If `debug` or `verbose` are bundled with local options - (not the global ones above), some logging may not show up until after - the local options are parsed. - * **Use Equals**: You can also include or not include an equals sign - `=` between options and values. - * **Quote Values**: When you need to quote an entire argument, such as - when using spaces, please use a combination of double quotes and - apostrophes (`"'value'"`). In cmd.exe you can just use double quotes - (`"value"`) but in powershell.exe you should use backticks - (`` `"value`" ``) or apostrophes (`'value'`). Using the combination - allows for both shells to work without issue, except for when the next - section applies. - * **Pass quotes in arguments**: When you need to pass quoted values to - to something like a native installer, you are in for a world of fun. In - cmd.exe you must pass it like this: `-ia "/yo=""Spaces spaces"""`. In - PowerShell.exe, you must pass it like this: `-ia '/yo=""Spaces spaces""'`. - No other combination will work. In PowerShell.exe if you are on version - v3+, you can try `--%` before `-ia` to just pass the args through as is, - which means it should not require any special workarounds. - * **Periods in PowerShell**: If you need to pass a period as part of a - value or a path, PowerShell doesn't always handle it well. Please - quote those values using "Quote Values" section above. - * Options and switches apply to all items passed, so if you are - installing multiple packages, and you use `--version=1.0.0`, choco - is going to look for and try to install version 1.0.0 of every - package passed. So please split out multiple package calls when - wanting to pass specific options. - -## Scripting / Integration - Best Practices / Style Guide - -When writing scripts, such as PowerShell scripts passing options and -switches, there are some best practices to follow to ensure that you -don't run into issues later. This also applies to integrations that -are calling Chocolatey and parsing output. Chocolatey **uses** -PowerShell, but it is an exe, so it cannot return PowerShell objects. - -Following these practices ensures both readability of your scripts AND -compatibility across different versions and editions of Chocolatey. -Following this guide will ensure your experience is not frustrating -based on choco not receiving things you think you are passing to it. - - * For consistency, always use `choco`, not `choco.exe`. - * Always have the command as the first argument to `choco`. e.g. - [`choco install`](xref:choco-command-install), where [`install`](xref:choco-command-install) is the command. - * If there is a subcommand, ensure that is the second argument. e.g. - `choco source list`, where `source` is the command and [`list`](xref:choco-command-list) is the - subcommand. - * Typically the subject comes next. If installing packages, the - subject would be the package names, e.g. `choco install pkg1 pkg2`. - * Never use 'nupkg' or point directly to a nupkg file UNLESS using - 'choco push'. Use the source folder instead, e.g. `choco install - --source="'c:\folder\with\package'"` instead of - `choco install DoNotDoThis.1.0.nupkg` or `choco install DoNotDoThis - --source="'c:\folder\with\package\DoNotDoThis.1.0.nupkg'"`. - * Switches and parameters are called simply options. Options come - after the subject. e.g. `choco install pkg1 --debug --verbose`. - * Never use the force option (`--force`/`-f`) in scripts (or really - otherwise as a default mode of use). Force is an override on - Chocolatey behavior. If you are wondering why Chocolatey isn't doing - something like the documentation says it should, it's likely because - you are using force. Stop. - * Always use full option name. If the short option is `-n`, and the - full option is `--name`, use `--name`. The only acceptable short - option for use in scripts is `-y`. Find option names in help docs - online or through `choco -?` /`choco [Command Name] -?`. - * For scripts that are running automated, always use `-y`. Do note - that even with `-y` passed, some things / state issues detected will - temporarily stop for input - the key here is temporarily. They will - continue without requiring any action after the temporary timeout - (typically 30 seconds). - * Full option names are prepended with two dashes, e.g. `--` or - `--debug --verbose --ignore-proxy`. - * When setting a value to an option, always put an equals (`=`) - between the name and the setting, e.g. `--source="'local'"`. - * When setting a value to an option, always surround the value - properly with double quotes bookending apostrophes, e.g. - `--source="'internal_server'"`. - * If you are building PowerShell scripts, you can most likely just - simply use apostrophes surrounding option values, e.g. - `--source='internal_server'`. - * Prefer upgrade to install in scripts. You can't [`install`](xref:choco-command-install) to a newer - version of something, but you can [`choco upgrade`](xref:choco-command-upgrade) which will do both - upgrade or install (unless switched off explicitly). - * If you are sharing the script with others, pass `--source` to be - explicit about where the package is coming from. Use full link and - not source name ('https://community.chocolatey.org/api/v2' versus - 'chocolatey'). - * If parsing output, you might want to use `--limit-output`/`-r` to - get output in a more machine parseable format. NOTE: Not all - commands handle return of information in an easily digestible - output. - * Use exit codes to determine status. Chocolatey exits with 0 when - everything worked appropriately and other exits codes like 1 when - things error. There are package specific exit codes that are - recommended to be used and reboot indicating exit codes as well. To - check exit code when using PowerShell, immediately call - `$exitCode = $LASTEXITCODE` to get the value choco exited with. - -Here's an example following bad practices (line breaks added for - readability): - - `choco install pkg1 -y -params '/Option:Value /Option2:value with - spaces' --c4b-option 'Yaass' --option-that-is-new 'dude upgrade'` - -Now here is that example written with best practices (again line - breaks added for readability - there are not line continuations - for choco): - - `choco upgrade pkg1 -y --source="'https://community.chocolatey.org/api/v2'" - --package-parameters="'/Option:Value /Option2:value with spaces'" - --c4b-option="'Yaass'" --option-that-is-new="'dude upgrade'"` - -Note the differences between the two: - * Which is more self-documenting? - * Which will allow for the newest version of something installed or - upgraded to (which allows for more environmental consistency on - packages and versions)? - * Which may throw an error on a badly passed option? - * Which will throw errors on unknown option values? See explanation - below. - -Chocolatey ignores options it doesn't understand, but it can only - ignore option values if they are tied to the option with an - equals sign ('='). Note those last two options in the examples above? - If you roll off of a commercial edition or someone with older version - attempts to run the badly crafted script `--c4b-option 'Yaass' - --option-that-is-new 'dude upgrade'`, they are likely to see errors on - 'Yaass' and 'dude upgrade' because they are not explicitly tied to the - option they are written after. Now compare that to the other script. - Choco will ignore `--c4b-option="'Yaass'"` and - `--option-that-is-new="'dude upgrade'"` as a whole when it doesn't - register the options. This means that your script doesn't error. - -Following these scripting best practices will ensure your scripts work - everywhere they are used and with newer versions of Chocolatey. - - -## See Help Menu In Action - -![choco help in action](/assets/images/gifs/choco_help.gif) - -## Default Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - -~~~ - - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco -h`. - diff --git a/input/en-us/choco/commands/info.md b/input/en-us/choco/commands/info.md deleted file mode 100644 index 5204569829..0000000000 --- a/input/en-us/choco/commands/info.md +++ /dev/null @@ -1,234 +0,0 @@ ---- -Order: 60 -xref: choco-command-info -Title: Info -Description: Info Command (choco info) -RedirectFrom: - - docs/commandsinfo - - docs/commands-info ---- - - - -# Info Command (choco info) - -Chocolatey will perform a search for a package local or remote and provide - detailed information about that package. This is a synonym for - `choco search --exact --detailed`. - - -## Usage - - choco info [] - -## Examples - - choco info chocolatey - choco info googlechrome - choco info powershell - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -Enhanced: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: no results (enhanced) - -> :choco-info: **NOTE** -> -> If you have the feature 'useEnhancedExitCodes' turned on, - then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -s, --source=VALUE - Source - Source location for install. Can use special 'windowsfeatures', - 'ruby', 'cygwin', or 'python' sources. Defaults to configured sources. - - -l, --lo, --localonly, --local-only - LocalOnly - Only search against local machine items. - - --version=VALUE - Version - Specific version of a package to return. - - --pre, --prerelease - Prerelease - Include Prereleases? Defaults to false. - - -u, --user=VALUE - User - used with authenticated feeds. Defaults to empty. - - -p, --password=VALUE - Password - the user's password to the source. Defaults to empty. - - --cert=VALUE - Client certificate - PFX pathname for an x509 authenticated feeds. - Defaults to empty. - - --cp, --certpassword=VALUE - Certificate Password - the client certificate's password to the source. - Defaults to empty. - - --disable-repository-optimizations, --disable-package-repository-optimizations - Disable Package Repository Optimizations - Do not use optimizations for - reducing bandwidth with repository queries during package - install/upgrade/outdated operations. Should not generally be used, - unless a repository needs to support older methods of query. When used, - this makes queries similar to the way they were done in earlier versions - of Chocolatey. Overrides the default feature - 'usePackageRepositoryOptimizations' set to 'True'. - - --include-configured-sources - Include Configured Sources - When using the '--source' option, this - appends the sources that have been saved into the chocolatey.config file - by 'source' command. Available in 2.3.0+ - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco info -h`. - diff --git a/input/en-us/choco/commands/install.md b/input/en-us/choco/commands/install.md deleted file mode 100644 index 08af939887..0000000000 --- a/input/en-us/choco/commands/install.md +++ /dev/null @@ -1,545 +0,0 @@ ---- -Order: 70 -xref: choco-command-install -Title: Install -Description: Install Command (choco install) -RedirectFrom: - - docs/commandsinstall - - docs/commands-install ---- - - - -# Install Command (choco install) - -Installs a package or a list of packages (sometimes specified as a - packages.config). - -## Usage - - choco install [ ] [] - -> :choco-info: **NOTE** -> -> Any package name ending with .config is considered a - 'packages.config' file. Please see https://ch0.co/packages_config - -> :choco-info: **NOTE** -> -> [Chocolatey Pro](https://chocolatey.org/compare) / Business builds on top of a great open source - experience with quite a few features that enhance the your use of the - community package repository (when using Pro), and really enhance the - Chocolatey experience all around. If you are an organization looking - for a better ROI, look no further than Business - automatic package - creation from installer files, automatic recompile support, runtime - malware protection, private CDN download cache, synchronize with - Programs and Features, etc - https://chocolatey.org/compare. - - -## Examples - - choco install sysinternals - choco install notepadplusplus googlechrome atom 7zip - choco install notepadplusplus --force --force-dependencies - choco install notepadplusplus googlechrome atom 7zip -dvfy - choco install git -y --params="'/GitAndUnixToolsOnPath /NoAutoCrlf'" - choco install git -y --params="'/GitAndUnixToolsOnPath /NoAutoCrlf'" --install-arguments="'/DIR=C:\git'" - # Params are package parameters, passed to the package - # Install args are installer arguments, appended to the silentArgs - # in the package for the installer itself - choco install nodejs.install --version 0.10.35 - choco install git -s "'https://somewhere/out/there'" - choco install git -s "'https://somewhere/protected'" -u user -p pass - -(DEPRECATED) Choco can also install directly from a nuspec/nupkg file. This aids in - testing packages: - - choco install - choco install - -> :choco-info: **NOTE** -> -> `all` is a special package keyword that will allow you to install - all packages available on a source. This keyword is not available for - public repositories like the Chocolatey [Community Repository](https://community.chocolatey.org/packages), and is - intended to be used with internal package sources only. - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -Package Exit Codes: - - 1641: success, reboot initiated - - 3010: success, reboot required - - other (not listed): likely an error has occurred - -In addition to normal exit codes, packages are allowed to exit - with their own codes when the feature 'usePackageExitCodes' is - turned on. Uninstall command has additional valid exit codes. - -Reboot Exit Codes: - - 350: pending reboot detected, no action has occurred - - 1604: install suspended, incomplete - -In addition to the above exit codes, you may also see reboot exit codes - when the feature 'exitOnRebootDetected' is turned on. It typically requires - the feature 'usePackageExitCodes' to also be turned on to work properly. - -## See It In Action - -Chocolatey FOSS install showing tab completion and `refreshenv` (a way - to update environment variables without restarting the shell). - -![FOSS install in action](/assets/images/gifs/choco_install.gif) - -[Chocolatey Professional](https://chocolatey.org/compare) showing private download cache and virus scan - protection. - -![Pro install in action](/assets/images/gifs/chocopro_install_stopped.gif) - -## Packages.config - -Alternative to PackageName. This is a list of packages in an xml manifest for Chocolatey to install. This is like the packages.config that NuGet uses except it also adds other options and switches. This can also be the path to the packages.config file if it is not in the current working directory. - -> :choco-info: **NOTE** -> -> The filename is only required to end in .config, the name is not required to be packages.config. - -~~~xml - - - - - - - -~~~ - - -## Alternative Sources - - -### Ruby -This specifies the source is Ruby Gems and that we are installing a - gem. If you do not have ruby installed prior to running this command, - the command will install that first. - e.g. `choco install compass -source ruby` - -### Cygwin -This specifies the source is Cygwin and that we are installing a cygwin - package, such as bash. If you do not have Cygwin installed, it will - install that first and then the product requested. - e.g. `choco install bash --source cygwin` - -### Python -This specifies the source is Python and that we are installing a python - package, such as Sphinx. If you do not have easy_install and Python - installed, it will install those first and then the product requested. - e.g. `choco install sphinx --source python` - -### Windows Features -This specifies that the source is a Windows Feature and we should - install via the Deployment Image Servicing and Management tool (DISM) - on the local machine. - e.g. `choco install IIS-WebServerRole --source windowsfeatures` - - -## Resources - - * How-To: A complete example of how you can use the PackageParameters argument - when creating a Chocolatey Package can be seen at - https://docs.chocolatey.org/en-us/guides/create/parse-packageparameters-argument - * One may want to override the default installation directory of a - piece of software. See - https://docs.chocolatey.org/en-us/getting-started#overriding-default-install-directory-or-other-advanced-install-concepts. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -s, --source=VALUE - Source - The source to find the package(s) to install. Special sources - include: ruby, cygwin, windowsfeatures, and python. To specify more than - one source, pass it with a semi-colon separating the values (e.g. - "'source1;source2'"). Defaults to default feeds. - - --version=VALUE - Version - A specific version to install. Defaults to unspecified. - - --pre, --prerelease - Prerelease - Include Prereleases? Defaults to false. - - --x86, --forcex86 - ForceX86 - Force x86 (32bit) installation on 64 bit systems. Defaults to - false. - - --ia, --installargs, --install-args, --installarguments, --install-arguments=VALUE - InstallArguments - Install Arguments to pass to the native installer in - the package. Defaults to unspecified. - - -o, --override, --overrideargs, --overridearguments, --override-arguments - OverrideArguments - Should install arguments be used exclusively without - appending to current package passed arguments? Defaults to false. - - --notsilent, --not-silent - NotSilent - Do not install this silently. Defaults to false. - - --params, --parameters, --pkgparameters, --packageparameters, --package-parameters=VALUE - PackageParameters - Parameters to pass to the package. Defaults to - unspecified. - - --argsglobal, --args-global, --installargsglobal, --install-args-global, --applyargstodependencies, --apply-args-to-dependencies, --apply-install-arguments-to-dependencies - Apply Install Arguments To Dependencies - Should install arguments be - applied to dependent packages? Defaults to false. - - --paramsglobal, --params-global, --packageparametersglobal, --package-parameters-global, --applyparamstodependencies, --apply-params-to-dependencies, --apply-package-parameters-to-dependencies - Apply Package Parameters To Dependencies - Should package parameters be - applied to dependent packages? Defaults to false. - - --allowdowngrade, --allow-downgrade - AllowDowngrade - Should an attempt at downgrading be allowed? Defaults - to false. - - -i, --ignoredependencies, --ignore-dependencies - IgnoreDependencies - Ignore dependencies when installing package(s). - Defaults to false. - - -x, --forcedependencies, --force-dependencies - ForceDependencies - Force dependencies to be reinstalled when force - installing package(s). Must be used in conjunction with --force. - Defaults to false. - - -n, --skippowershell, --skip-powershell, --skipscripts, --skip-scripts, --skip-automation-scripts - Skip PowerShell - Do not run chocolateyInstall.ps1. Defaults to false. - - -u, --user=VALUE - User - used with authenticated feeds. Defaults to empty. - - -p, --password=VALUE - Password - the user's password to the source. Defaults to empty. - - --cert=VALUE - Client certificate - PFX pathname for an x509 authenticated feeds. - Defaults to empty. - - --cp, --certpassword=VALUE - Certificate Password - the client certificate's password to the source. - Defaults to empty. - - --ignorechecksum, --ignore-checksum, --ignorechecksums, --ignore-checksums - IgnoreChecksums - Ignore checksums provided by the package. Overrides - the default feature 'checksumFiles' set to 'True'. - - --allowemptychecksum, --allowemptychecksums, --allow-empty-checksums - Allow Empty Checksums - Allow packages to have empty/missing checksums - for downloaded resources from non-secure locations (HTTP, FTP). Use this - switch is not recommended if using sources that download resources from - the internet. Overrides the default feature 'allowEmptyChecksums' set to - 'False'. - - --allowemptychecksumsecure, --allowemptychecksumssecure, --allow-empty-checksums-secure - Allow Empty Checksums Secure - Allow packages to have empty checksums - for downloaded resources from secure locations (HTTPS). Overrides the - default feature 'allowEmptyChecksumsSecure' set to 'True'. - - --requirechecksum, --requirechecksums, --require-checksums - Require Checksums - Requires packages to have checksums for downloaded - resources (both non-secure and secure). Overrides the default feature - 'allowEmptyChecksums' set to 'False' and 'allowEmptyChecksumsSecure' set - to 'True'. - - --checksum, --downloadchecksum, --download-checksum=VALUE - Download Checksum - a user provided checksum for downloaded resources - for the package. Overrides the package checksum (if it has one). - Defaults to empty. - - --checksum64, --checksumx64, --downloadchecksumx64, --download-checksum-x64=VALUE - Download Checksum 64bit - a user provided checksum for 64bit downloaded - resources for the package. Overrides the package 64-bit checksum (if it - has one). Defaults to same as Download Checksum. - - --checksumtype, --checksum-type, --downloadchecksumtype, --download-checksum-type=VALUE - Download Checksum Type - a user provided checksum type. Overrides the - package checksum type (if it has one). Used in conjunction with Download - Checksum. Available values are 'md5', 'sha1', 'sha256' or 'sha512'. - Defaults to 'md5'. - - --checksumtype64, --checksumtypex64, --checksum-type-x64, --downloadchecksumtypex64, --download-checksum-type-x64=VALUE - Download Checksum Type 64bit - a user provided checksum for 64bit - downloaded resources for the package. Overrides the package 64-bit - checksum (if it has one). Used in conjunction with Download Checksum - 64bit. Available values are 'md5', 'sha1', 'sha256' or 'sha512'. - Defaults to same as Download Checksum Type. - - --ignorepackagecodes, --ignorepackageexitcodes, --ignore-package-codes, --ignore-package-exit-codes - IgnorePackageExitCodes - Exit with a 0 for success and 1 for non-succes- - s, no matter what package scripts provide for exit codes. Overrides the - default feature 'usePackageExitCodes' set to 'True'. - - --usepackagecodes, --usepackageexitcodes, --use-package-codes, --use-package-exit-codes - UsePackageExitCodes - Package scripts can provide exit codes. Use those - for choco's exit code when non-zero (this value can come from a - dependency package). Chocolatey defines valid exit codes as 0, 1605, - 1614, 1641, 3010. Overrides the default feature 'usePackageExitCodes' - set to 'True'. - - --stoponfirstfailure, --stop-on-first-failure, --stop-on-first-package-failure - Stop On First Package Failure - stop running install, upgrade or - uninstall on first package failure instead of continuing with others. - Overrides the default feature 'stopOnFirstPackageFailure' set to 'False'. - - --exitwhenrebootdetected, --exit-when-reboot-detected - Exit When Reboot Detected - Stop running install, upgrade, or uninstall - when a reboot request is detected. Requires 'usePackageExitCodes' - feature to be turned on. Will exit with either 350 or 1604. Overrides - the default feature 'exitOnRebootDetected' set to 'False'. - - --ignoredetectedreboot, --ignore-detected-reboot - Ignore Detected Reboot - Ignore any detected reboots if found. Overrides - the default feature 'exitOnRebootDetected' set to 'False'. - - --disable-repository-optimizations, --disable-package-repository-optimizations - Disable Package Repository Optimizations - Do not use optimizations for - reducing bandwidth with repository queries during package - install/upgrade/outdated operations. Should not generally be used, - unless a repository needs to support older methods of query. When used, - this makes queries similar to the way they were done in earlier versions - of Chocolatey. Overrides the default feature - 'usePackageRepositoryOptimizations' set to 'True'. - - --pin, --pinpackage, --pin-package - Pin Package - Add a pin to the package after install. Available in 1.2.0+ - - --skiphooks, --skip-hooks - Skip hooks - Do not run hook scripts. Available in 1.2.0+ - - --include-configured-sources - Include Configured Sources - When using the '--source' option, this - appends the sources that have been saved into the chocolatey.config file - by 'source' command. Available in 2.3.0+ - - --sdc, --skipdownloadcache, --skip-download-cache - Skip Download Cache - Use the original download even if a private CDN - cache is available for a package. Overrides the default feature - 'downloadCache' set to 'True'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/private-cdn - - --dc, --downloadcache, --download-cache, --use-download-cache - Use Download Cache - Use private CDN cache if available for a package. - Overrides the default feature 'downloadCache' set to 'True'. Licensed - editions only. - See https://docs.chocolatey.org/en-us/features/private-cdn - - --svc, --skipvirus, --skip-virus, --skipviruscheck, --skip-virus-check - Skip Virus Check - Skip the virus check for downloaded files on this ru- - n. Overrides the default feature 'virusCheck' set to 'False'. Licensed - editions only. - See https://docs.chocolatey.org/en-us/features/virus-check - - --virus, --viruscheck, --virus-check - Virus Check - check downloaded files for viruses. Overrides the default - feature 'virusCheck' set to 'False'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/virus-check - - --viruspositivesmin, --virus-positives-minimum=VALUE - Virus Check Minimum Scan Result Positives - the minimum number of scan - result positives required to flag a package. Used when virusScannerType - is VirusTotal. Overrides the default configuration value - 'virusCheckMinimumPositives' set to '4'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/virus-check - - --install-arguments-sensitive=VALUE - InstallArgumentsSensitive - Install Arguments to pass to the native - installer in the package that are sensitive and you do not want logged. - Defaults to unspecified. Licensed editions only. - - --package-parameters-sensitive=VALUE - PackageParametersSensitive - Package Parameters to pass the package that - are sensitive and you do not want logged. Defaults to unspecified. - Licensed editions only. - - --dir, --directory, --installdir, --installdirectory, --install-dir, --install-directory=VALUE - Install Directory Override - Override the default installation directory. - Chocolatey will automatically determine the type of installer and - pass the appropriate arguments to override the install directory. The - package must use Chocolatey install helpers and be installing an - installer for software. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/install-directory-override - - --bps, --maxdownloadrate, --max-download-rate, --maxdownloadbitspersecond, --max-download-bits-per-second, --maximumdownloadbitspersecond, --maximum-download-bits-per-second=VALUE - Maximum Download Rate Bits Per Second - The maximum download rate in - bits per second. '0' or empty means no maximum. A number means that will - be the maximum download rate in bps. Defaults to config setting of '0'. - Available in licensed editions only. - See https://docs.chocolatey.org/en-us/features/package-throttle - - --reduce, --reduce-package-size, --deflate, --deflate-package-size - Reducer Installed Package Size (Package Reducer) - Reduce size of the - nupkg file to very small and remove extracted archives and installers. - Overrides the default feature 'reduceInstalledPackageSpaceUsage' set to - 'True'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/package-reducer - - --no-reduce, --no-reduce-package-size, --no-deflate, --no-deflate-package-size - Do Not Reduce Installed Package Size - Leave the nupkg and files alone - in the package. Overrides the default feature - 'reduceInstalledPackageSpaceUsage' set to 'True'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/package-reducer - - --reduce-nupkg-only, --deflate-nupkg-only - Reduce Only Nupkg File Size - reduce only the size of nupkg file when - using Package Reducer. Overrides the default feature - 'reduceOnlyNupkgSize' set to 'False'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/package-reducer - - --reason, --pin-reason, --note=VALUE - Pin Reason - Text information about why you are setting a pin. Available - in business editions 5.0.0+. - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco install -h`. - diff --git a/input/en-us/choco/commands/list.md b/input/en-us/choco/commands/list.md deleted file mode 100644 index fcdd460489..0000000000 --- a/input/en-us/choco/commands/list.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -Order: 80 -xref: choco-command-list -Title: List -Description: List Command (choco list) -RedirectFrom: - - docs/commandslist - - docs/commands-list ---- - - - -# List Command (choco list) - -## Usage - - choco list [] - -## Examples - - choco list -i - choco list --include-programs - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -Enhanced: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: no results (enhanced) - -> :choco-info: **NOTE** -> -> If you have the feature 'useEnhancedExitCodes' turned on, - then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -s, --source=VALUE - Source - Name of alternative source to use, for example - 'windowsfeatures', 'ruby', 'cygwin', or 'python'. - - --idonly, --id-only - Id Only - Only return Package Ids in the list results. - - --pre, --prerelease - Prerelease - Include Prereleases? Defaults to false. - - -i, --includeprograms, --include-programs - IncludePrograms - Includes software from Programs and Features not being - managed by Chocolatey CLI. - - --version=VALUE - Version - Specific version of a package to return. - - --page=VALUE - Page - the 'page' of results to return. Defaults to return all results. - - --page-size=VALUE - Page Size - the amount of package results to return per page. Defaults - to 25. - - -e, --exact - Exact - Only return packages with this exact name. - - --by-id-only - ByIdOnly - Only return packages where the id contains the search filter. - - --by-tag-only, --by-tags-only - ByTagOnly - Only return packages where the search filter matches on the - tags. - - --id-starts-with - IdStartsWith - Only return packages where the id starts with the search - filter. - - --detail, --detailed - Detailed - Alias for verbose. - - --audit, --showaudit, --show-audit, --show-audit-info - Show Audit Information - Display auditing information for a package. - Available in business editions only. - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco list -h`. - diff --git a/input/en-us/choco/commands/optimize.md b/input/en-us/choco/commands/optimize.md deleted file mode 100644 index d4d032ea48..0000000000 --- a/input/en-us/choco/commands/optimize.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -Order: 90 -xref: choco-command-optimize -Title: Optimize -Description: Optimize Command (choco optimize) -RedirectFrom: - - docs/commandsoptimize - - docs/commands-optimize ---- - - - -# Optimize Command (choco optimize) - -### Package Optimizer - -Chocolatey [Licensed editions](https://chocolatey.org/compare) only. - -Similar to Package Reducer, but reduces for existing packages. -With Package Optimizer/Reducer: - -* nupkg file is reduced to 5KB or less, no matter the size. -* zips / installers are automatically removed from the package directory if they are found. -* zips / installers are removed from TEMP cache if found. - -The following file extensions are removed automatically: - -* 7z / zip / rar / gz / tar / sfx -* iso -* msi / msu / msp -* exe files if they are detected to be an installer - - - -## Usage - - choco optimize [] - -## Examples - - choco optimize - choco optimize --reduce-nupkg-only - - -## See It In Action - -Coming soon - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - downloading multiple packages, and you use `--version=1.0.0`, it is - going to look for and try to download version 1.0.0 of every package - - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - --reduce-nupkg-only, --deflate-nupkg-only - Reduce Only Nupkg File Size - reduce only the size of nupkg file when - using Package Optimizer. Licensed editions only. - - --id=VALUE - Id - The package to optimize - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco optimize -h`. - diff --git a/input/en-us/choco/commands/outdated.md b/input/en-us/choco/commands/outdated.md deleted file mode 100644 index 7d5193ac81..0000000000 --- a/input/en-us/choco/commands/outdated.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -Order: 100 -xref: choco-command-outdated -Title: Outdated -Description: Outdated Command (choco outdated) -RedirectFrom: - - docs/commandsoutdated - - docs/commands-outdated ---- - - - -# Outdated Command (choco outdated) - -Returns a list of outdated packages. - - -## Usage - - choco outdated [] - -## Examples - - choco outdated - choco outdated -s https://somewhere/out/there - choco outdated -s "'https://somewhere/protected'" -u user -p pass - -If you use `--source=https://somewhere/out/there`, it is - going to look for outdated packages only based on that source, so - you may want to add `--ignore-unfound` to your options. - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -Enhanced: - - 0: no outdated packages - - -1 or 1: an error has occurred - - 2: outdated packages have been found (enhanced) - -> :choco-info: **NOTE** -> -> If you have the feature 'useEnhancedExitCodes' turned on, - then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## See It In Action - -![choco outdated](/assets/images/gifs/choco_outdated.gif) - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -s, --source=VALUE - Source - The source to find the package(s) to install. Special sources - include: ruby, cygwin, windowsfeatures, and python. To specify more than - one source, pass it with a semi-colon separating the values (e.g. - "'source1;source2'"). Defaults to default feeds. - - -u, --user=VALUE - User - used with authenticated feeds. Defaults to empty. - - -p, --password=VALUE - Password - the user's password to the source. Defaults to empty. - - --cert=VALUE - Client certificate - PFX pathname for an x509 authenticated feeds. - Defaults to empty. - - --cp, --certpassword=VALUE - Certificate Password - the client certificate's password to the source. - Defaults to empty. - - --pre, --prerelease - Prerelease - Include Prereleases? Defaults to false. - - --ignore-pinned - Ignore Pinned - Ignore pinned packages. Defaults to false. - - --ignore-unfound - Ignore Unfound Packages - Ignore packages that are not found on the - sources used (or the defaults). Overrides the default feature - 'ignoreUnfoundPackagesOnUpgradeOutdated' set to 'False'. - - --disable-repository-optimizations, --disable-package-repository-optimizations - Disable Package Repository Optimizations - Do not use optimizations for - reducing bandwidth with repository queries during package - install/upgrade/outdated operations. Should not generally be used, - unless a repository needs to support older methods of query. When - disabled, this makes queries similar to the way they were done in - earlier versions of Chocolatey. Overrides the default feature - 'usePackageRepositoryOptimizations' set to 'True'. - - --include-configured-sources - Include Configured Sources - When using the '--source' option, this - appends the sources that have been saved into the chocolatey.config file - by 'source' command. Available in 2.3.0+ - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco outdated -h`. - diff --git a/input/en-us/choco/commands/pin.md b/input/en-us/choco/commands/pin.md deleted file mode 100644 index 52c2ce4a30..0000000000 --- a/input/en-us/choco/commands/pin.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -Order: 110 -xref: choco-command-pin -Title: Pin -Description: Pin Command (choco pin) -RedirectFrom: - - docs/commandspin - - docs/commands-pin ---- - - - -# Pin Command (choco pin) - -Pin a package to suppress upgrades. - -This is especially helpful when running [`choco upgrade`](xref:choco-command-upgrade) for all - packages, as it will automatically skip those packages. Another - alternative is `choco upgrade --except="pkg1,pk2"`. - -## Usage - - choco pin [list]|add|remove [] - -## Examples - - choco pin - choco pin list - choco pin add -n git - choco pin add --name="'git'" --version="'1.2.3'" - choco pin add --name="'git'" --version="'1.2.3'" --reason="'reasons available in business editions only'" - choco pin remove --name="'git'" - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: nothing to do (enhanced) - -> :choco-info: **NOTE** -> -> Starting in v2.3.0, if you have the feature 'useEnhancedExitCodes' - turned on, then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -n, --name=VALUE - Name - the name of the package. Required with some actions. Defaults to - empty. - - --version=VALUE - Version - Used when multiple versions of a package are installed. - Defaults to empty. - - --reason, --pin-reason, --note=VALUE - Pin Reason - Text information about why you are setting a pin. Available - in business editions only. - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco pin -h`. - diff --git a/input/en-us/choco/commands/rule.md b/input/en-us/choco/commands/rule.md deleted file mode 100644 index 17afcf42d2..0000000000 --- a/input/en-us/choco/commands/rule.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -Order: 115 -xref: choco-command-rule -Title: Rule -Description: Rule Command (choco rule) -RedirectFrom: - - docs/commandsrule - - docs/commands-rule ---- - - - -# Rule Command (choco rule) - -> :choco-warning: **WARNING** -> -> This command was introduced in Chocolatey CLI v2.3.0 - -Retrieve information about what rule validations are implemented by Chocolatey CLI. - -## Usage - - choco rule [list]|get [options/switches] - -## Examples - - choco rule - choco rule list - choco rule get --name CHCR0002 - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -n, --name=VALUE - Name - the name of the rule to show more details about. Required with - actions other than list. Defaults to empty. -Press enter to continue... - - -~~~ - -[Command Reference](xref:choco-commands) - - -*> :choco-info: **NOTE*** This documentation has been automatically generated from `choco rule -h`. - diff --git a/input/en-us/choco/commands/search.md b/input/en-us/choco/commands/search.md deleted file mode 100644 index 5c93ec3797..0000000000 --- a/input/en-us/choco/commands/search.md +++ /dev/null @@ -1,289 +0,0 @@ ---- -Order: 120 -xref: choco-command-search -Title: Search -Description: Search Command (choco search) -RedirectFrom: - - docs/commandssearch - - docs/commands-search ---- - - - -# Search Command (choco search) - -Chocolatey will perform a search for a package local or remote. - -## Usage - - choco find [] - choco search [] - -## Examples - - choco search git - choco search git --source="'https://somewhere/out/there'" - choco search bob -s "'https://somewhere/protected'" -u user -p pass - choco search --page=0 --page-size=25 - choco search 7zip --all-versions --exact - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -Enhanced: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: no results (enhanced) - -> :choco-info: **NOTE** -> -> If you have the feature 'useEnhancedExitCodes' turned on, - then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## See It In Action - -![choco search](/assets/images/gifs/choco_search.gif) - - -## Alternative Sources -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -s, --source=VALUE - Source - Source location for install. Can use special 'windowsfeatures', - 'ruby', 'cygwin', or 'python' sources. Defaults to sources. - - --idonly, --id-only - Id Only - Only return Package Ids in the list results. - - --pre, --prerelease - Prerelease - Include Prereleases? Defaults to false. - - -i, --includeprograms, --include-programs - IncludePrograms - Filters out apps Chocolatey has listed as packages and - includes those in the list. Defaults to false. - - -a, --all, --allversions, --all-versions - AllVersions - include results from all versions. - - --version=VALUE - Version - Specific version of a package to return. - - -u, --user=VALUE - User - used with authenticated feeds. Defaults to empty. - - -p, --password=VALUE - Password - the user's password to the source. Defaults to empty. - - --cert=VALUE - Client certificate - PFX pathname for an x509 authenticated feeds. - Defaults to empty. - - --cp, --certpassword=VALUE - Certificate Password - the client certificate's password to the source. - Defaults to empty. - - --page=VALUE - Page - the 'page' of results to return. Defaults to return all results. - - --page-size=VALUE - Page Size - the amount of packages to return in each page of results. - NOTE: this value is per source. Defaults to 25 for each source that is - included in query. - - -e, --exact - Exact - Only return packages with this exact name. - - --by-id-only - ByIdOnly - Only return packages where the id contains the search filter. - - --by-tag-only, --by-tags-only - ByTagOnly - Only return packages where the search filter matches on the - tags. - - --id-starts-with - IdStartsWith - Only return packages where the id starts with the search - filter. - - --order-by-popularity - OrderByPopularity - Sort by package results by popularity. - - --approved-only - ApprovedOnly - Only return approved packages - this option will filter - out results not from the [community repository](https://community.chocolatey.org/packages). - - --download-cache, --download-cache-only - DownloadCacheAvailable - Only return packages that have a download cache - available - this option will filter out results not from the community - repository. - - --not-broken - NotBroken - Only return packages that are not failing testing - this - option only filters out failing results from the [community feed](https://community.chocolatey.org/packages). It will - not filter against other sources. - - --detail, --detailed - Detailed - Alias for verbose. - - --disable-repository-optimizations, --disable-package-repository-optimizations - Disable Package Repository Optimizations - Do not use optimizations for - reducing bandwidth with repository queries during package - install/upgrade/outdated operations. Should not generally be used, - unless a repository needs to support older methods of query. When - disabled, this makes queries similar to the way they were done in - earlier versions of Chocolatey. Overrides the default feature - 'usePackageRepositoryOptimizations' set to 'True'. - - --include-configured-sources - Include Configured Sources - When using the '--source' option, this - appends the sources that have been saved into the chocolatey.config file - by 'source' command. Available in 2.3.0+ - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco search -h`. - diff --git a/input/en-us/choco/commands/setapikey.md b/input/en-us/choco/commands/setapikey.md deleted file mode 100644 index 4360fb42b4..0000000000 --- a/input/en-us/choco/commands/setapikey.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -Order: 130 -xref: choco-command-setapikey -Title: SetApiKey -Description: SetApiKey Command (choco setapikey) -RedirectFrom: - - docs/commandssetapikey - - docs/commands-setapikey ---- - - - -# ApiKey Command (choco setapikey) - -This lists API keys that are set or sets an api key for a particular - source so it doesn't need to be specified every time. - -Anything that doesn't contain source and key will list API keys. - -## Usage - - choco apikey [] - choco setapikey [] - -## Examples - - choco apikey - choco apikey -s https://somewhere/out/there - choco apikey list - choco apikey list -s https://somewhere/out/there - choco apikey add -s="https://somewhere/out/there/" -k="value" - choco apikey add -s "https://push.chocolatey.org/" -k="123-123123-123" - choco apikey add -s "http://internal_nexus" -k="user:password" - choco apikey remove -s https://somewhere/out/there - -For source location, this can be a folder/file share or an -http location. When it comes to urls, they can be different from the packages -url (where packages are searched and installed from). As an example, for -Chocolatey's community package package repository, the package url is -https://community.chocolatey.org/api/v2/, but the push url is https://push.chocolatey.org -(and the deprecated https://chocolatey.org/ as a push url). Check the -documentation for your choice of repository to learn what the push url is. - -For the key, this can be an apikey that is provided by your source repository. -With some sources, like Nexus, this can be a NuGet API key or it could be a -user name and password specified as 'user:password' for the API key. Please see -your repository's documentation (for Nexus, please see -https://ch0.co/nexus2apikey). - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Connecting to Chocolatey.org (Community Package Repository) - -In order to save your API key for https://push.chocolatey.org/, - log in (or register, confirm and then log in) to - https://push.chocolatey.org/, go to https://push.chocolatey.org/account, - copy the API Key, and then use it in the following command: - - choco apikey add -k -s https://push.chocolatey.org/ - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: nothing to do, apikey already set (enhanced) - -> :choco-info: **NOTE** -> -> Starting in v2.3.0, if you have the feature 'useEnhancedExitCodes' - turned on, then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -s, --source=VALUE - Source [REQUIRED] - The source location for the key - - -k, --key, --apikey, --api-key=VALUE - ApiKey - The API key for the source. This is the authentication that - identifies you and allows you to push to a source. With some sources - this is either a key or it could be a user name and password specified - as 'user:password'. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco setapikey -h`. - diff --git a/input/en-us/choco/commands/source.md b/input/en-us/choco/commands/source.md deleted file mode 100644 index 5bfe5fba6b..0000000000 --- a/input/en-us/choco/commands/source.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -Order: 140 -xref: choco-command-source -Title: Source -Description: Source Command (choco source) -RedirectFrom: - - docs/commandssource - - docs/commands-source ---- - - - -# Source Command (choco source) - -Chocolatey will allow you to interact with sources. - -## Usage - - choco source [list]|add|remove|disable|enable [] - choco sources [list]|add|remove|disable|enable [] - -## Examples - - choco source - choco source list - choco source add -n=bob -s="https://somewhere/out/there/api/v2/" - choco source add -n=bob -s "'https://somewhere/out/there/api/v2/'" -cert=\Users\bob\bob.pfx - choco source add -n=bob -s "'https://somewhere/out/there/api/v2/'" -u=bob -p=12345 - choco source disable -n=bob - choco source enable -n=bob - choco source remove -n=bob - -When it comes to the source location, this can be a folder/file share or an http -location. If it is a url, it will be a location you can go to in a browser and -it returns OData with something that says Packages in the browser, similar to -what you see when you go to https://community.chocolatey.org/api/v2/. - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: nothing to do (enhanced) - -> :choco-info: **NOTE** -> -> Starting in v2.3.0, if you have the feature 'useEnhancedExitCodes' - turned on, then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -n, --name=VALUE - Name - the name of the source. Required with actions other than list. - Defaults to empty. - - -s, --source=VALUE - Source - The source. This can be a folder/file share or an http locatio- - n. If it is a url, it will be a location you can go to in a browser and - it returns OData with something that says Packages in the browser, - similar to what you see when you go to https://community.chocolate- - y.org/api/v2/. Required with add action. Defaults to empty. - - -u, --user=VALUE - User - used with authenticated feeds. Defaults to empty. - - -p, --password=VALUE - Password - the user's password to the source. Encrypted in chocolate- - y.config file. - - --cert=VALUE - Client certificate - PFX pathname for an x509 authenticated feeds. - Defaults to empty. - - --cp, --certpassword=VALUE - Certificate Password - the client certificate's password to the source. - Defaults to empty. - - --priority=VALUE - Priority - The priority order of this source as compared to other - sources, lower is better. Defaults to 0 (no priority). All priorities - above 0 will be evaluated first, then zero-based values will be - evaluated in config file order. - - --bypassproxy, --bypass-proxy - Bypass Proxy - Should this source explicitly bypass any explicitly or - system configured proxies? Defaults to false. - - --allowselfservice, --allow-self-service - Allow Self-Service - Should this source be allowed to be used with self- - service? Requires business edition with feature - 'useBackgroundServiceWithSelfServiceSourcesOnly' turned on. Defaults to - false. - - --adminonly, --admin-only - Visible to Administrators Only - Should this source be visible to non- - administrators? Requires business edition. Defaults to false. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco source -h`. - diff --git a/input/en-us/choco/commands/sources.md b/input/en-us/choco/commands/sources.md deleted file mode 100644 index 5a61c0aa70..0000000000 --- a/input/en-us/choco/commands/sources.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -Order: 150 -xref: choco-command-sources -Title: Sources -Description: Sources Command (choco sources) -RedirectFrom: - - docs/commandssources - - docs/commands-sources ---- - - - -# Source Command (choco sources) - -Chocolatey will allow you to interact with sources. - -## Usage - - choco source [list]|add|remove|disable|enable [] - choco sources [list]|add|remove|disable|enable [] - -## Examples - - choco source - choco source list - choco source add -n=bob -s="https://somewhere/out/there/api/v2/" - choco source add -n=bob -s "'https://somewhere/out/there/api/v2/'" -cert=\Users\bob\bob.pfx - choco source add -n=bob -s "'https://somewhere/out/there/api/v2/'" -u=bob -p=12345 - choco source disable -n=bob - choco source enable -n=bob - choco source remove -n=bob - -When it comes to the source location, this can be a folder/file share or an http -location. If it is a url, it will be a location you can go to in a browser and -it returns OData with something that says Packages in the browser, similar to -what you see when you go to https://community.chocolatey.org/api/v2/. - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: nothing to do (enhanced) - -> :choco-info: **NOTE** -> -> Starting in v2.3.0, if you have the feature 'useEnhancedExitCodes' - turned on, then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -n, --name=VALUE - Name - the name of the source. Required with actions other than list. - Defaults to empty. - - -s, --source=VALUE - Source - The source. This can be a folder/file share or an http locatio- - n. If it is a url, it will be a location you can go to in a browser and - it returns OData with something that says Packages in the browser, - similar to what you see when you go to https://community.chocolate- - y.org/api/v2/. Required with add action. Defaults to empty. - - -u, --user=VALUE - User - used with authenticated feeds. Defaults to empty. - - -p, --password=VALUE - Password - the user's password to the source. Encrypted in chocolate- - y.config file. - - --cert=VALUE - Client certificate - PFX pathname for an x509 authenticated feeds. - Defaults to empty. - - --cp, --certpassword=VALUE - Certificate Password - the client certificate's password to the source. - Defaults to empty. - - --priority=VALUE - Priority - The priority order of this source as compared to other - sources, lower is better. Defaults to 0 (no priority). All priorities - above 0 will be evaluated first, then zero-based values will be - evaluated in config file order. - - --bypassproxy, --bypass-proxy - Bypass Proxy - Should this source explicitly bypass any explicitly or - system configured proxies? Defaults to false. - - --allowselfservice, --allow-self-service - Allow Self-Service - Should this source be allowed to be used with self- - service? Requires business edition with feature - 'useBackgroundServiceWithSelfServiceSourcesOnly' turned on. Defaults to - false. - - --adminonly, --admin-only - Visible to Administrators Only - Should this source be visible to non- - administrators? Requires business edition. Defaults to false. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco sources -h`. - diff --git a/input/en-us/choco/commands/support.md b/input/en-us/choco/commands/support.md deleted file mode 100644 index 25bc31b5b4..0000000000 --- a/input/en-us/choco/commands/support.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -Order: 160 -xref: choco-command-support -Title: Support -Description: Support Command (choco support) -RedirectFrom: - - docs/commandssupport - - docs/commands-support ---- - - - -# Support Command (choco support) - -As a licensed customer, you can reach out to - our email for support. If you have phone support, you - may reach out during the hours that are listed in your support - contract. See https://chocolatey.org/support for details. - -## Usage - - choco support [] - -## Examples - - choco support - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco support -h`. - diff --git a/input/en-us/choco/commands/sync.md b/input/en-us/choco/commands/sync.md deleted file mode 100644 index 4b429bb56d..0000000000 --- a/input/en-us/choco/commands/sync.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -Order: 170 -xref: choco-command-sync -Title: Sync -Description: Sync Command (choco sync) -RedirectFrom: - - docs/commandssync - - docs/commands-sync ---- - - - -# Synchronize Command (choco sync) - -Business editions of Chocolatey only. - -Synchronizes against the system installed software that are not - installed as packages on Chocolatey. Searches through the system to - see software that has been installed and generates packages from that - software, baselines the packages against Chocolatey and makes the - packages available to upload to source. - -See https://docs.chocolatey.org/en-us/features/package-synchronization/ - - -## Usage - - choco sync [] - -## Examples - - choco sync - choco sync --id=putty - choco sync --id=putty --package-id=putty - -## See It In Action - -Coming soon - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - downloading multiple packages, and you use `--version=1.0.0`, it is - going to look for and try to download version 1.0.0 of every package - - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - --id=VALUE - Id - The Display Name from Programs and Features - - --packageid, --package-id=VALUE - PackageId - When used with Id, this will be the custom name for the - package. Business editions only. - - --out, --outdir, --outputdirectory, --output-directory=VALUE - OutputDirectory - Specifies the directory for the generated Chocolatey - package file(s). If not specified, uses a subdirectory of the current - directory. - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco sync -h`. - diff --git a/input/en-us/choco/commands/synchronize.md b/input/en-us/choco/commands/synchronize.md deleted file mode 100644 index 073aa05184..0000000000 --- a/input/en-us/choco/commands/synchronize.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -Order: 180 -xref: choco-command-synchronize -Title: Synchronize -Description: Synchronize Command (choco synchronize) -RedirectFrom: - - docs/commandssynchronize - - docs/commands-synchronize ---- - - - -# Synchronize Command (choco synchronize) - -Business editions of Chocolatey only. - -Synchronizes against the system installed software that are not - installed as packages on Chocolatey. Searches through the system to - see software that has been installed and generates packages from that - software, baselines the packages against Chocolatey and makes the - packages available to upload to source. - -See https://docs.chocolatey.org/en-us/features/package-synchronization/ - - -## Usage - - choco sync [] - -## Examples - - choco sync - choco sync --id=putty - choco sync --id=putty --package-id=putty - -## See It In Action - -Coming soon - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - downloading multiple packages, and you use `--version=1.0.0`, it is - going to look for and try to download version 1.0.0 of every package - - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - --id=VALUE - Id - The Display Name from Programs and Features - - --packageid, --package-id=VALUE - PackageId - When used with Id, this will be the custom name for the - package. Business editions only. - - --out, --outdir, --outputdirectory, --output-directory=VALUE - OutputDirectory - Specifies the directory for the generated Chocolatey - package file(s). If not specified, uses a subdirectory of the current - directory. - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco synchronize -h`. - diff --git a/input/en-us/choco/commands/uninstall.md b/input/en-us/choco/commands/uninstall.md deleted file mode 100644 index 9728cf6e0f..0000000000 --- a/input/en-us/choco/commands/uninstall.md +++ /dev/null @@ -1,344 +0,0 @@ ---- -Order: 190 -xref: choco-command-uninstall -Title: Uninstall -Description: Uninstall Command (choco uninstall) -RedirectFrom: - - docs/commandsuninstall - - docs/commands-uninstall ---- - - - -# Uninstall Command (choco uninstall) - -Uninstalls a package or a list of packages. - -Chocolatey automatically tracks registry changes for "Programs and - Features" of the underlying software's native installers when - installing packages. The "Automatic Uninstaller" (auto uninstaller) - service is a feature that can use that information to automatically - determine how to uninstall these natively installed applications. This - means that a package may not need an explicit chocolateyUninstall.ps1 - to reverse the installation done in the install script. - -Chocolatey tracks packages, which are the files in - `$env:ChocolateyInstall\lib\packagename`. These packages may or may not - contain the software (applications/tools) that each package represents. - The software may actually be installed in Program Files (most native - installers will install the software there) or elsewhere on the - machine. - -With auto uninstaller turned off, a chocolateyUninstall.ps1 is required - to perform uninstall from the system. In the absence of - chocolateyUninstall.ps1, choco uninstall only removes the package from - Chocolatey but does not remove the software from your system (unless - in the package directory). - -> :choco-info: **NOTE** -> -> A package with a failing uninstall can be removed with the -`-n --skipautouninstaller` flags. This will remove the package from -chocolatey without attempting to uninstall the program. - -> :choco-info: **NOTE** -> -> [Chocolatey Pro](https://chocolatey.org/compare) / Business automatically synchronizes with - Programs and Features, ensuring manually removed apps are - automatically removed from Chocolatey's repository. - -> :choco-info: **NOTE** -> -> Synchronizer and AutoUninstaller enhancements in licensed - versions of Chocolatey ensure that Autouninstaller is up to 95% - effective at removing software without an uninstall script. This is - because synchronizer ensures the registry snapshot stays up to date - and licensed enhancements have the ability to inspect more locations - to determine how to automatically uninstall software. - -## Usage - - choco uninstall [pkg2 pkgN] [options/switches] - -> :choco-info: **NOTE** -> -> `all` is a special package keyword that will allow you to - uninstall all packages. - - -## See It In Action - -![choco uninstall](/assets/images/gifs/choco_uninstall.gif) - - -## Examples - - choco uninstall git - choco uninstall notepadplusplus googlechrome atom 7zip - choco uninstall notepadplusplus googlechrome atom 7zip -dv - choco uninstall ruby --version 1.8.7.37402 - choco uninstall nodejs.install --all-versions - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -Package Exit Codes: - - 1605: software is not installed - - 1614: product is uninstalled - - 1641: success, reboot initiated - - 3010: success, reboot required - - other (not listed): likely an error has occurred - -In addition to normal exit codes, packages are allowed to exit - with their own codes when the feature 'usePackageExitCodes' is - turned on. - -Reboot Exit Codes: - - 350: pending reboot detected, no action has occurred - - 1604: install suspended, incomplete - -In addition to the above exit codes, you may also see reboot exit codes - when the feature 'exitOnRebootDetected' is turned on. It typically requires - the feature 'usePackageExitCodes' to also be turned on to work properly. - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -s, --source=VALUE - Source - The source to find the package(s) to install. Special sources - include: ruby, cygwin, windowsfeatures, and python. Defaults to default - feeds. - - --version=VALUE - Version - A specific version to uninstall. Defaults to unspecified. - - -a, --allversions, --all-versions - AllVersions - Uninstall all versions? Defaults to false. - - --ua, --uninstallargs, --uninstallarguments, --uninstall-arguments=VALUE - UninstallArguments - Uninstall Arguments to pass to the native installer - in the package. Defaults to unspecified. - - -o, --override, --overrideargs, --overridearguments, --override-arguments - OverrideArguments - Should uninstall arguments be used exclusively - without appending to current package passed arguments? Defaults to false. - - --notsilent, --not-silent - NotSilent - Do not uninstall this silently. Defaults to false. - - --params, --parameters, --pkgparameters, --packageparameters, --package-parameters=VALUE - PackageParameters - Parameters to pass to the package. Defaults to - unspecified. - - --argsglobal, --args-global, --installargsglobal, --install-args-global, --applyargstodependencies, --apply-args-to-dependencies, --apply-install-arguments-to-dependencies - Apply Install Arguments To Dependencies - Should install arguments be - applied to dependent packages? Defaults to false. - - --paramsglobal, --params-global, --packageparametersglobal, --package-parameters-global, --applyparamstodependencies, --apply-params-to-dependencies, --apply-package-parameters-to-dependencies - Apply Package Parameters To Dependencies - Should package parameters be - applied to dependent packages? Defaults to false. - - -x, --forcedependencies, --force-dependencies, --removedependencies, --remove-dependencies - RemoveDependencies - Uninstall dependencies when uninstalling package(s- - ). Defaults to false. - - -n, --skippowershell, --skip-powershell, --skipscripts, --skip-scripts, --skip-automation-scripts - Skip PowerShell - Do not run chocolateyUninstall.ps1. Defaults to false. - - --ignorepackagecodes, --ignorepackageexitcodes, --ignore-package-codes, --ignore-package-exit-codes - IgnorePackageExitCodes - Exit with a 0 for success and 1 for non-succes- - s, no matter what package scripts provide for exit codes. Overrides the - default feature 'usePackageExitCodes' set to 'True'. - - --usepackagecodes, --usepackageexitcodes, --use-package-codes, --use-package-exit-codes - UsePackageExitCodes - Package scripts can provide exit codes. Use those - for choco's exit code when non-zero (this value can come from a - dependency package). Chocolatey defines valid exit codes as 0, 1605, - 1614, 1641, 3010. Overrides the default feature 'usePackageExitCodes' - set to 'True'. - - --autouninstaller, --use-autouninstaller - UseAutoUninstaller - Use auto uninstaller service when uninstalling. - Overrides the default feature 'autoUninstaller' set to 'True'. - - --skipautouninstaller, --skip-autouninstaller - SkipAutoUninstaller - Skip auto uninstaller service when uninstalling. - Overrides the default feature 'autoUninstaller' set to 'True'. - - --failonautouninstaller, --fail-on-autouninstaller - FailOnAutoUninstaller - Fail the package uninstall if the auto - uninstaller reports and error. Overrides the default feature - 'failOnAutoUninstaller' set to 'False'. - - --ignoreautouninstallerfailure, --ignore-autouninstaller-failure - Ignore Auto Uninstaller Failure - Do not fail the package if auto - uninstaller reports an error. Overrides the default feature - 'failOnAutoUninstaller' set to 'False'. - - --stoponfirstfailure, --stop-on-first-failure, --stop-on-first-package-failure - Stop On First Package Failure - stop running install, upgrade or - uninstall on first package failure instead of continuing with others. - Overrides the default feature 'stopOnFirstPackageFailure' set to 'False'. - - --exitwhenrebootdetected, --exit-when-reboot-detected - Exit When Reboot Detected - Stop running install, upgrade, or uninstall - when a reboot request is detected. Requires 'usePackageExitCodes' - feature to be turned on. Will exit with either 350 or 1604. Overrides - the default feature 'exitOnRebootDetected' set to 'False'. - - --ignoredetectedreboot, --ignore-detected-reboot - Ignore Detected Reboot - Ignore any detected reboots if found. Overrides - the default feature 'exitOnRebootDetected' set to 'False'. - - --skiphooks, --skip-hooks - Skip hooks - Do not run hook scripts. Available in 1.2.0+ - - --fromprograms, --from-programs, --fromprogramsandfeatures, --from-programs-and-features - From Programs and Features - Uninstalls a program from programs and - features. Name used for id must be a match or a wildcard (*) to Display - Name in Programs and Features. Available in licensed editions only. - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco uninstall -h`. - diff --git a/input/en-us/choco/commands/unpackself.md b/input/en-us/choco/commands/unpackself.md deleted file mode 100644 index 6442b45221..0000000000 --- a/input/en-us/choco/commands/unpackself.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -Order: 200 -xref: choco-command-unpackself -Title: UnpackSelf -Description: UnpackSelf Command (choco unpackself) -RedirectFrom: - - docs/commandsunpackself - - docs/commands-unpackself ---- - - - -# [DEPRECATED] UnpackSelf Command (choco unpackself) - -> :choco-info: **NOTE** -> -> Unpackself has been deprecated and will be removed in version 3.0.0. - -This will unpack files needed by choco. It will overwrite existing - files only if --force is specified. - -> :choco-info: **NOTE** -> -> This command should only be used when installing Chocolatey, not - during normal operation. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco unpackself -h`. - diff --git a/input/en-us/choco/commands/upgrade.md b/input/en-us/choco/commands/upgrade.md deleted file mode 100644 index ab25bbbb4e..0000000000 --- a/input/en-us/choco/commands/upgrade.md +++ /dev/null @@ -1,528 +0,0 @@ ---- -Order: 220 -xref: choco-command-upgrade -Title: Upgrade -Description: Upgrade Command (choco upgrade) -RedirectFrom: - - docs/commandsupgrade - - docs/commands-upgrade ---- - - - -# Upgrade Command (choco upgrade) - -Upgrades a package or a list of packages. If you do not have a package - installed, upgrade will install it. - -## Usage - - choco upgrade [ ] [] - -> :choco-info: **NOTE** -> -> `all` is a special package keyword that will allow you to upgrade - all currently installed packages. - -Skip upgrading certain packages with [`choco pin`](xref:choco-command-pin) or with the option - `--except`. - -> :choco-info: **NOTE** -> -> [Chocolatey Pro](https://chocolatey.org/compare) / Business automatically synchronizes with - Programs and Features, ensuring automatically updating apps' versions - (like Chrome) are up to date in Chocolatey's repository. - -## Examples - - choco upgrade chocolatey - choco upgrade notepadplusplus googlechrome atom 7zip - choco upgrade notepadplusplus googlechrome atom 7zip -dvfy - choco upgrade git -y --params="'/GitAndUnixToolsOnPath /NoAutoCrlf'" - choco upgrade git -y --params="'/GitAndUnixToolsOnPath /NoAutoCrlf'" --install-args="'/DIR=C:\git'" - # Params are package parameters, passed to the package - # Install args are installer arguments, appended to the silentArgs - # in the package for the installer itself - choco upgrade nodejs.install --version 0.10.35 - choco upgrade git -s "'https://somewhere/out/there'" - choco upgrade git -s "'https://somewhere/protected'" -u user -p pass - choco upgrade all - choco upgrade all --except="'skype,conemu'" - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: nothing to do, no packages outdated (enhanced) - -> :choco-info: **NOTE** -> -> Starting in v2.3.0, if you have the feature 'useEnhancedExitCodes' - turned on, then choco will provide enhanced exit codes that allow - better integration and scripting. - -Package Exit Codes: - - 1641: success, reboot initiated - - 3010: success, reboot required - - other (not listed): likely an error has occurred - -In addition to normal exit codes, packages are allowed to exit - with their own codes when the feature 'usePackageExitCodes' is - turned on. Uninstall command has additional valid exit codes. - -Reboot Exit Codes: - - 350: pending reboot detected, no action has occurred - - 1604: install suspended, incomplete - -In addition to the above exit codes, you may also see reboot exit codes - when the feature 'exitOnRebootDetected' is turned on. It typically requires - the feature 'usePackageExitCodes' to also be turned on to work properly. - -## See It In Action - -![choco upgrade](/assets/images/gifs/choco_upgrade.gif) - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -s, --source=VALUE - Source - The source to find the package(s) to install. Special sources - include: ruby, cygwin, windowsfeatures, and python. To specify more than - one source, pass it with a semi-colon separating the values (e.g. - "'source1;source2'"). Defaults to default feeds. - - --version=VALUE - Version - A specific version to install. Defaults to unspecified. - - --pre, --prerelease - Prerelease - Include Prereleases? Defaults to false. - - --x86, --forcex86 - ForceX86 - Force x86 (32bit) installation on 64 bit systems. Defaults to - false. - - --ia, --installargs, --install-args, --installarguments, --install-arguments=VALUE - InstallArguments - Install Arguments to pass to the native installer in - the package. Defaults to unspecified. - - -o, --override, --overrideargs, --overridearguments, --override-arguments - OverrideArguments - Should install arguments be used exclusively without - appending to current package passed arguments? Defaults to false. - - --notsilent, --not-silent - NotSilent - Do not install this silently. Defaults to false. - - --params, --parameters, --pkgparameters, --packageparameters, --package-parameters=VALUE - PackageParameters - Parameters to pass to the package. Defaults to - unspecified. - - --argsglobal, --args-global, --installargsglobal, --install-args-global, --applyargstodependencies, --apply-args-to-dependencies, --apply-install-arguments-to-dependencies - Apply Install Arguments To Dependencies - Should install arguments be - applied to dependent packages? Defaults to false. - - --paramsglobal, --params-global, --packageparametersglobal, --package-parameters-global, --applyparamstodependencies, --apply-params-to-dependencies, --apply-package-parameters-to-dependencies - Apply Package Parameters To Dependencies - Should package parameters be - applied to dependent packages? Defaults to false. - - --allowdowngrade, --allow-downgrade - AllowDowngrade - Should an attempt at downgrading be allowed? Defaults - to false. - - -i, --ignoredependencies, --ignore-dependencies - IgnoreDependencies - Ignore dependencies when upgrading package(s). - Defaults to false. - - -n, --skippowershell, --skip-powershell, --skipscripts, --skip-scripts, --skip-automation-scripts - Skip PowerShell - Do not run chocolateyInstall.ps1. Defaults to false. - - --failonunfound, --fail-on-unfound - Fail On Unfound Packages - If a package is not found in sources - specified, fail instead of warn. - - --ignore-unfound - Ignore Unfound Packages - Ignore packages that are not found on the - sources used (or the defaults). Overrides the default feature - 'ignoreUnfoundPackagesOnUpgradeOutdated' set to 'False'. - - --failonnotinstalled, --fail-on-not-installed - Fail On Non-installed Packages - If a package is not already installed, - fail instead of installing. - - -u, --user=VALUE - User - used with authenticated feeds. Defaults to empty. - - -p, --password=VALUE - Password - the user's password to the source. Defaults to empty. - - --cert=VALUE - Client certificate - PFX pathname for an x509 authenticated feeds. - Defaults to empty. - - --cp, --certpassword=VALUE - Certificate Password - the client certificate's password to the source. - Defaults to empty. - - --ignorechecksum, --ignore-checksum, --ignorechecksums, --ignore-checksums - IgnoreChecksums - Ignore checksums provided by the package. Overrides - the default feature 'checksumFiles' set to 'True'. - - --allowemptychecksum, --allowemptychecksums, --allow-empty-checksums - Allow Empty Checksums - Allow packages to have empty/missing checksums - for downloaded resources from non-secure locations (HTTP, FTP). Use this - switch is not recommended if using sources that download resources from - the internet. Overrides the default feature 'allowEmptyChecksums' set to - 'False'. - - --allowemptychecksumsecure, --allowemptychecksumssecure, --allow-empty-checksums-secure - Allow Empty Checksums Secure - Allow packages to have empty checksums - for downloaded resources from secure locations (HTTPS). Overrides the - default feature 'allowEmptyChecksumsSecure' set to 'True'. - - --requirechecksum, --requirechecksums, --require-checksums - Require Checksums - Requires packages to have checksums for downloaded - resources (both non-secure and secure). Overrides the default feature - 'allowEmptyChecksums' set to 'False' and 'allowEmptyChecksumsSecure' set - to 'True'. - - --checksum, --downloadchecksum, --download-checksum=VALUE - Download Checksum - a user provided checksum for downloaded resources - for the package. Overrides the package checksum (if it has one). - Defaults to empty. - - --checksum64, --checksumx64, --downloadchecksumx64, --download-checksum-x64=VALUE - Download Checksum 64bit - a user provided checksum for 64bit downloaded - resources for the package. Overrides the package 64-bit checksum (if it - has one). Defaults to same as Download Checksum. - - --checksumtype, --checksum-type, --downloadchecksumtype, --download-checksum-type=VALUE - Download Checksum Type - a user provided checksum type. Overrides the - package checksum type (if it has one). Used in conjunction with Download - Checksum. Available values are 'md5', 'sha1', 'sha256' or 'sha512'. - Defaults to 'md5'. - - --checksumtype64, --checksumtypex64, --checksum-type-x64, --downloadchecksumtypex64, --download-checksum-type-x64=VALUE - Download Checksum Type 64bit - a user provided checksum for 64bit - downloaded resources for the package. Overrides the package 64-bit - checksum (if it has one). Used in conjunction with Download Checksum - 64bit. Available values are 'md5', 'sha1', 'sha256' or 'sha512'. - Defaults to same as Download Checksum Type. - - --ignorepackagecodes, --ignorepackageexitcodes, --ignore-package-codes, --ignore-package-exit-codes - IgnorePackageExitCodes - Exit with a 0 for success and 1 for non-succes- - s, no matter what package scripts provide for exit codes. Overrides the - default feature 'usePackageExitCodes' set to 'True'. - - --usepackagecodes, --usepackageexitcodes, --use-package-codes, --use-package-exit-codes - UsePackageExitCodes - Package scripts can provide exit codes. Use those - for choco's exit code when non-zero (this value can come from a - dependency package). Chocolatey defines valid exit codes as 0, 1605, - 1614, 1641, 3010. Overrides the default feature 'usePackageExitCodes' - set to 'True'. - - --except=VALUE - Except - a comma-separated list of package names that should not be - upgraded when upgrading 'all'. Overrides the configuration setting - 'upgradeAllExceptions' set to ''. - - --stoponfirstfailure, --stop-on-first-failure, --stop-on-first-package-failure - Stop On First Package Failure - stop running install, upgrade or - uninstall on first package failure instead of continuing with others. - Overrides the default feature 'stopOnFirstPackageFailure' set to 'False'. - - --skip-if-not-installed, --only-upgrade-installed, --skip-when-not-installed - Skip Packages Not Installed - if a package is not installed, do not - install it during the upgrade process. Overrides the default feature - 'skipPackageUpgradesWhenNotInstalled' set to 'False'. - - --install-if-not-installed - Install Missing Packages When Not Installed - if a package is not - installed, install it as part of running upgrade (typically default - behavior). Overrides the default feature - 'skipPackageUpgradesWhenNotInstalled' set to 'False'. - - --exclude-pre, --exclude-prerelease, --exclude-prereleases - Exclude Prerelease - Should prerelease be ignored for upgrades? Will be - ignored if you pass `--pre`. - - --userememberedargs, --userememberedarguments, --userememberedoptions, --use-remembered-args, --use-remembered-arguments, --use-remembered-options - Use Remembered Options for Upgrade - use the arguments and options used - during install for upgrade. Does not override arguments being passed at - runtime. Overrides the default feature - 'useRememberedArgumentsForUpgrades' set to 'False'. - - --ignorerememberedargs, --ignorerememberedarguments, --ignorerememberedoptions, --ignore-remembered-args, --ignore-remembered-arguments, --ignore-remembered-options - Ignore Remembered Options for Upgrade - ignore the arguments and options - used during install for upgrade. Overrides the default feature - 'useRememberedArgumentsForUpgrades' set to 'False'. - - --exitwhenrebootdetected, --exit-when-reboot-detected - Exit When Reboot Detected - Stop running install, upgrade, or uninstall - when a reboot request is detected. Requires 'usePackageExitCodes' - feature to be turned on. Will exit with either 350 or 1604. Overrides - the default feature 'exitOnRebootDetected' set to 'False'. - - --ignoredetectedreboot, --ignore-detected-reboot - Ignore Detected Reboot - Ignore any detected reboots if found. Overrides - the default feature 'exitOnRebootDetected' set to 'False'. - - --disable-repository-optimizations, --disable-package-repository-optimizations - Disable Package Repository Optimizations - Do not use optimizations for - reducing bandwidth with repository queries during package - install/upgrade/outdated operations. Should not generally be used, - unless a repository needs to support older methods of query. When - disabled, this makes queries similar to the way they were done in - earlier versions of Chocolatey. Overrides the default feature - 'usePackageRepositoryOptimizations' set to 'True'. - - --pin, --pinpackage, --pin-package - Pin Package - Add a pin to the package after upgrade. Available in 1.2.0+ - - --skiphooks, --skip-hooks - Skip hooks - Do not run hook scripts. Available in 1.2.0+ - - --ignore-pinned - Ignore Pinned - Ignores any pins and upgrades the package(s) anyway. - Available in 2.3.0+ - - --include-configured-sources - Include Configured Sources - When using the '--source' option, this - appends the sources that have been saved into the chocolatey.config file - by 'source' command. Available in 2.3.0+ - - --sdc, --skipdownloadcache, --skip-download-cache - Skip Download Cache - Use the original download even if a private CDN - cache is available for a package. Overrides the default feature - 'downloadCache' set to 'True'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/private-cdn - - --dc, --downloadcache, --download-cache, --use-download-cache - Use Download Cache - Use private CDN cache if available for a package. - Overrides the default feature 'downloadCache' set to 'True'. - Licensed editions only. - See https://docs.chocolatey.org/en-us/features/private-cdn - - --svc, --skipvirus, --skip-virus, --skipviruscheck, --skip-virus-check - Skip Virus Check - Skip the virus check for downloaded files on this ru- - n. Overrides the default feature 'virusCheck' set to 'False'. - Licensed editions only. - See https://docs.chocolatey.org/en-us/features/virus-check - - --virus, --viruscheck, --virus-check - Virus Check - check downloaded files for viruses. Overrides the default - feature 'virusCheck' set to 'False'. - Licensed editions only. - See https://docs.chocolatey.org/en-us/features/virus-check - - --viruspositivesmin, --virus-positives-minimum=VALUE - Virus Check Minimum Scan Result Positives - the minimum number of scan - result positives required to flag a package. Used when virusScannerType - is VirusTotal. Overrides the default configuration value - 'virusCheckMinimumPositives' set to '4'. Licensed - editions only. - See https://docs.chocolatey.org/en-us/features/virus-check - - --install-arguments-sensitive=VALUE - InstallArgumentsSensitive - Install Arguments to pass to the native - installer in the package that are sensitive and you do not want logged. - Defaults to unspecified. Licensed editions only. - - --package-parameters-sensitive=VALUE - PackageParametersSensitive - Package Parameters to pass the package that - are sensitive and you do not want logged. Defaults to unspecified. - Licensed editions only. - - --dir, --directory, --installdir, --installdirectory, --install-dir, --install-directory=VALUE - Install Directory Override - Override the default installation director- - y. Chocolatey will automatically determine the type of installer and - pass the appropriate arguments to override the install directory. The - package must use Chocolatey install helpers and be installing an - installer for software. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/install-directory-override - - --bps, --maxdownloadrate, --max-download-rate, --maxdownloadbitspersecond, --max-download-bits-per-second, --maximumdownloadbitspersecond, --maximum-download-bits-per-second=VALUE - Maximum Download Rate Bits Per Second - The maximum download rate in - bits per second. '0' or empty means no maximum. A number means that will - be the maximum download rate in bps. Defaults to config setting of '0'. - Available in licensed editions only. - See https://docs.chocolatey.org/en-us/features/package-throttle - - --reduce, --reduce-package-size, --deflate, --deflate-package-size - Reducer Installed Package Size (Package Reducer) - Reduce size of the - nupkg file to very small and remove extracted archives and installers. - Overrides the default feature 'reduceInstalledPackageSpaceUsage' set to - 'True'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/package-reducer - - --no-reduce, --no-reduce-package-size, --no-deflate, --no-deflate-package-size - Do Not Reduce Installed Package Size - Leave the nupkg and files alone - in the package. Overrides the default feature - 'reduceInstalledPackageSpaceUsage' set to 'True'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/package-reducer - - --reduce-nupkg-only, --deflate-nupkg-only - Reduce Only Nupkg File Size - reduce only the size of nupkg file when - using Package Reducer. Overrides the default feature - 'reduceOnlyNupkgSize' set to 'False'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/package-reducer - - --exclude-chocolatey-packages-during-upgrade-all - Exclude Chocolatey Packages During Upgrade All - When running the 'choco - upgrade all' command, do not upgrade any of the official Chocolatey - packages. Overrides the default feature - 'excludeChocolateyPackagesDuringUpgradeAll' set to 'False'. Licensed - editions only. - - --include-chocolatey-packages-during-upgrade-all - Include Chocolatey Package During Upgrade All - When running the 'choco - upgrade all' command, include all the official Chocolatey packages. - Overrides the default feature - 'excludeChocolateyPackagesDuringUpgradeAll' set to 'False'. Licensed - editions only. - - --reason, --pin-reason, --note=VALUE - Pin Reason - Text information about why you are setting a pin. Available - in business editions 5.0.0+. - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco upgrade -h`. - diff --git a/input/en-us/choco/features/http-caching.md b/input/en-us/choco/features/http-caching.md deleted file mode 100644 index e4800c0146..0000000000 --- a/input/en-us/choco/features/http-caching.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -Order: 10 -xref: choco-http-caching -Title: HTTP Caching in Chocolatey CLI -Description: Information about the HTTP caching functionality in Chocolatey CLI ---- - -> :choco-info: **NOTE** -> -> HTTP Caching was introduced in Chocolatey CLI v2.0.0 and is unavailable to earlier versions. - -> :choco-warning: **WARNING** -> -> HTTP caching is still considered experimental and is subject to change in future versions of Chocolatey CLI. - -Chocolatey CLI introduces HTTP Caching to minimize the time taken for subsequent checks for the same packages when they need to be looked up multiple times as part of an install, upgrade, search, or checking for outdated packages. - -At the time of writing, only some things reaching out to Chocolatey/NuGet feeds are cached. In general, the only HTTP requests that Chocolatey CLI will cache are responses from the feeds for specific package versions or if we request all package versions. -This caching behavior occurs for both v2 and v3 API feeds. - -## Locations for HTTP Cache - -There are two locations where Chocolatey CLI will store HTTP caches. -This location will depend entirely on the context in which you are launching Chocolatey CLI. - -Suppose you launch Chocolatey CLI in an elevated context (As an administrator). In that case, the HTTP cache will be read and stored from `C:\ProgramData\ChocolateyHttpCache`. - -When you launch Chocolatey CLI in a non-elevated context, the HTTP cache will be read and stored underneath your user profile. This location will look similar to `C:\Users\\.chocolatey\http-cache` (**replace `` with your logged in username**). - -These two locations are entirely separate, and launching in an elevated context will not read the cache stored for non-elevated executions. Non-elevated executions will not read the cache from elevated executions. - -## HTTP Cache Expiration - -> :choco-warning: **WARNING** -> -> The time before HTTP cache expiration is likely to be changed in the future. - -Any created HTTP cache will be valid for 30 minutes. After this time has passed, any new requests made for the cached items will reach out to the appropriate feeds again and replace the expired cache with the new response. - -It is important to note that Chocolatey CLI will not remove any caches, but rather a request to the cached call replaces it. - -### What To Do if Experiencing Problems With Caching / Force Up To Date Requests - -It is necessary to make manual changes if you are experiencing problems with the caching solution or want to force Chocolatey CLI to get the latest up-to-date information. - -Suppose you are experiencing problems with the caching solution or want to force Chocolatey CLI to get the latest information. In that case, you will need to delete the cached data manually. Refer to [Locations for HTTP Cache](#locations-for-http-cache) to find the appropriate cache location for your use case. Removing all files in these locations will clear the cached data and prompt Chocolatey CLI to reach out to the relevant feeds when it next needs that data. - -> :choco-info: **NOTE** -> -> In a future version, we expect to add alternative methods to skip, ignore or clear the cache directories through Chocolatey CLI. diff --git a/input/en-us/choco/features/index.md b/input/en-us/choco/features/index.md deleted file mode 100644 index 18209166b8..0000000000 --- a/input/en-us/choco/features/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 90 -xref: choco-features -Title: Features -Description: This is the main entry point for available features in Chocolatey CLI ---- \ No newline at end of file diff --git a/input/en-us/choco/features/version-number-normalization.md b/input/en-us/choco/features/version-number-normalization.md deleted file mode 100644 index 42ee9b2899..0000000000 --- a/input/en-us/choco/features/version-number-normalization.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -Order: 20 -xref: version-normalization -Title: Version Number Normalization -Description: Information about the version number normalization introduced in Chocolatey CLI 2.0.0. ---- - -The release of Chocolatey CLI 2.0.0 brought with it new semantic version number requirements. To comply with these new requirements, Chocolatey CLI will normalize version numbers to at least three parts, and remove leading zeroes. - -* Version numbers that have fewer than three parts will have missing parts added, as `0` (for example, `1.2` will be normalized to `1.2.0`). -* Version numbers that have four parts, will have the fourth part removed if it is `0` (for example, `1.0.0.0` will be normalized to `1.0.0`, but `1.0.0.1` will not). -* Version numbers that have leading zeroes in any part will have those leading zeroes removed (for example, `1.001.2` will be normalized to `1.1.2`). - -This normalization is applied to the generated package when using `choco pack` under Chocolatey CLI 2.x onwards, and will also affect any displayed versions of packages from remote sources. - -This is a change from how Chocolatey CLI 1.x worked with version numbers. - -## Special Consideration For Package Maintainers - -Many Chocolatey package scripts use the `$env:ChocolateyPackageVersion` environment variable. As version number normalization affects the package version number, the expected behaviour of the package may be affected. Our recommendation is to use a version number explicitly, rather than relying on the contents of `$env:ChocolateyPackageVersion`. See the [PowerShell Environmental Variables Reference](xref:powershell-reference#environment-variables) for more information. diff --git a/input/en-us/choco/index.md b/input/en-us/choco/index.md deleted file mode 100644 index 0869e577f0..0000000000 --- a/input/en-us/choco/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 90 -xref: choco -Title: Chocolatey CLI (choco) -Description: This is the main entry point for using Chocolatey, use choco.exe to install/upgrade packages ---- \ No newline at end of file diff --git a/input/en-us/choco/new-in-v2.md b/input/en-us/choco/new-in-v2.md deleted file mode 100644 index f432ae592c..0000000000 --- a/input/en-us/choco/new-in-v2.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -Order: 15 -xref: choco-new-in-v2 -Title: What's new in Chocolatey CLI v2.0.0 -Description: A summary of the notable differences when upgrading from Chocolatey CLI v1.x to v2.0.0 ---- - -# What's New in Chocolatey CLI v2.0.0 - -> **Note** -> -> This is a high-level overview of what's new in Chocolatey CLI 2.0.0. If you are ready to upgrade, please read the [upgrade guide](xref:upgrading-to-chocolatey-v2-v6). - -## NuGet v3 Feed Support - -You can now use NuGet v3 package feeds with Chocolatey CLI! -This allows users to work with package repositories that provide NuGet v3 feeds. -We will be adding NuGet v3 support to the Chocolatey Community Repository in the future. - -Listed below are some examples of repository managers that support NuGet v3 feeds, that you can start using with Chocolatey CLI v2.0.0 and later: - -- [GitHub Packages](https://github.com/features/packages) -- [ProGet](https://inedo.com/proget) -- [Sonatype Nexus](https://www.sonatype.com/products/sonatype-nexus-repository) -- [JFrog Artifactory](https://jfrog.com/artifactory/) - -## SemVer 2.0.0 Support - -Starting in v2.0.0, Chocolatey CLI supports SemVer 2.0.0, although it requires that all version number segments fit into the range `0-2147483647`. -This allows some additional prerelease package version variants like `1.0.1-alpha.23` (note the period in the prerelease tag following the hyphen, which was previously considered not valid for a version number) to be built with Chocolatey CLI. -For more information on SemVer 2.0.0, please see [the SemVer website](https://semver.org/spec/v2.0.0.html). - -> **Note** -> -> Most older version styles, like 4-part version numbers (`1.0.0.2`), are still supported. -> Chocolatey CLI v2.0.0 and later adopt NuGet's current versioning system. -> Any version numbers supported by NuGet are also supported by Chocolatey CLI. - -## Minimum Operating System Support Changes - -See our [Support Lifecycle](xref:chocolatey-components-dependencies-and-support-lifecycle) page for a full run-down. - -> **Note** -> -> To use the Chocolatey Community Repository with Windows Server 2008 R2 and 2012, you need to ensure the relevant patches are installed and registry entries configured to enable TLS v1.2 by default. - -## .NET Framework Uplift - -Chocolatey CLI v2.0.0 now requires .NET Framework 4.8. -When possible, the installation process will attempt to install .NET Framework 4.8 if it's not already present on the system. -However, installing .NET Framework 4.8 will require a reboot to be completed before Chocolatey CLI can be installed. - -For the smoothest upgrade experience, we recommend you install .NET Framework 4.8 and reboot before installing or upgrading to Chocolatey CLI v2.0.0. - -## API Key Subcommands - -The `choco apikey` syntax has changed. -The `--remove` option has been removed, and `add` / `remove` / `list` subcommands have been added. -For example: - -```powershell -choco apikey add --source "'https://source.url/api/v2/'" --key "'API_KEY_HERE'" -choco apikey list -choco apikey remove --source "'https://source.url/api/v2/'" -``` - -For backwards compatibility, omitting the subcommand retains its original behaviour: - -- `choco apikey` with no arguments defaults to `list`, listing stored API keys. -- `choco apikey --source "'https://source.url/api/v2/'" --key "'API_KEY_HERE'"` with both arguments defaults to `add`, adding a new API key. - -## Builtin Shims Removed - -For a long time Chocolatey CLI provided shortcuts for commands like `choco pack` (`cpack`) and `choco install` (`cinst`). -This has led to some conflicts with other software and we [deprecated these shortcuts, also called _shims_](https://github.com/chocolatey/choco/issues/2641). -We have now [removed them entirely](https://github.com/chocolatey/choco/issues/2642). - -If you miss that functionality, it is still possible to add these commands back as either batch files on the PATH, or PowerShell functions added to your profile. - -## The List Command Only Shows Local Packages - -Previously, Chocolatey CLI had three identical commands: `list`, `search`, and `find`. -In v2.0.0, `list` has become the command used for listing locally-installed packages, while `search` and `find` work with remote repositories. -For backwards compatibility, the `-lo` and `--local-only` flags are deprecated when using limited output `--limited-output`, with plans to remove them in Chocolatey CLI v3.0.0. -Usage without the `--limited-output` argument will return an error when `-lo` or `--local-only` is used. - -## Limits On Large Queries - -Chocolatey CLI will now impose a limit on the number of packages returned by the `list`, `find`, and `search` commands. -For local sources the limit is **10,000** packages, with remote sources being limited to **1,000**. -The default page size in both cases is **25**. -On reaching these limits, Chocolatey CLI will warn you to refine your query to get the results you need. - -## Added Options, Configurations, and Features - -- `--online` option added for commands' `--help`. - This will now take you to an online version of the command help. - For example, `choco install --help --online` will open the [Install command docs page](https://docs.chocolatey.org/en-us/choco/commands/install) in your default browser. -- `choco feature` now supports the `get` subcommand, which will show a single feature state. -- The `defaultPushSource` configuration option was added, which sets a default URL to push to when using `choco push`. - -## Removed Options and Features - -- Removed the deprecated side-by-side install functionality (aka `--allow-multiple`). -- Removed the deprecated default push location of `push.chocolatey.org`. - Use the new `defaultPushSource` configuration instead (see above). -- Removed deprecated configuration options for `cacheLocation` and `commandExecutionTimeoutSettings`. -- Only Chocolatey CLI configuration is shown for `choco config list`. - Use `choco feature list` to view features, and `choco apikey list` to view API key entries. -- [WebPi has been removed by Microsoft](https://github.com/chocolatey/choco/issues/2958) and the `--source webpi` alternative package source has been removed. -- Removed installing directly from a `nupkg` or `nuspec` file. - Use `choco install packagename -s ./local/path/to/folder` instead, and ensure packages are packed with `choco pack` before attempting to install them. -- Package version numbers will no longer retain leading zeroes in any parts of the version number when using `choco pack`. - For example, `09.00.001` will be normalized to `9.0.1`. - -## Ready To Upgrade? - -If you are ready to upgrade, please read our [upgrade guide](xref:upgrading-to-chocolatey-v2-v6). diff --git a/input/en-us/choco/release-notes.md b/input/en-us/choco/release-notes.md deleted file mode 100644 index 98ba1f1942..0000000000 --- a/input/en-us/choco/release-notes.md +++ /dev/null @@ -1,2525 +0,0 @@ ---- -Order: 10 -xref: choco-release-notes -Title: Release Notes -Description: Release Notes for Chocolatey CLI -OgImage: https://img.chocolatey.org/social-share/release-notes-chocolatey-cli-og.png -TwitterImage: https://img.chocolatey.org/social-share/release-notes-chocolatey-cli-twitter.png -RedirectFrom: docs/release-notes-choco-cli ---- - -# Chocolatey Release Notes - Open Source - -This covers changes for the "chocolatey" and "chocolatey.lib" packages, which are available as FOSS. - -> :choco-info: **NOTE** -> -> For commercial editions, please also refer to [Licensed Release Notes](xref:setup-licensed). - - - - - - -## 2.3.0 (June 5, 2024){#v2.3.0} - -Read our [blog post](https://blog.chocolatey.org/2024/06/announcing-cli-230-cle-620-agent213-releases/) about this release. - -### Deprecated Feature - -- Deprecate `unpackself` command - see [#3426](https://github.com/chocolatey/choco/issues/3426). - -### Features - -- Save software install location for future use - see [#3315](https://github.com/chocolatey/choco/issues/3315). -- Allow viewing package creation validation rules via new `choco rule` command - see [#3381](https://github.com/chocolatey/choco/issues/3381). - -### Bug Fixes - -- Fix - Ensure `Install-ChocolateyInstallPackage` does not add a trailing space to silent arguments - see [#2345](https://github.com/chocolatey/choco/issues/2345). -- Fix - Ensure `Install-ChocolateyPath` adds a new entry to the PATH when part of it is already there - see [#3318](https://github.com/chocolatey/choco/issues/3318). -- Fix - Using `Install-ChocolateyPath -PathType Machine` in a non-admin context spawns PowerShell endlessly and never completes - see [#3424](https://github.com/chocolatey/choco/issues/3424). - -### Improvements - -- Allow all packages from a source to be installed - see [#23](https://github.com/chocolatey/choco/issues/23). -- Allow the ability to add the configured sources when using the `--source` option - see [#72](https://github.com/chocolatey/choco/issues/72). -- Add `Uninstall-ChocolateyPath` function to manage removing entries from PATH - see [#310](https://github.com/chocolatey/choco/issues/310). -- Verify the checksum of a package before installation, and fail if not matched - see [#1144](https://github.com/chocolatey/choco/issues/1144). -- Show remembered arguments for packages - see [#1310](https://github.com/chocolatey/choco/issues/1310). -- Add the source URL where the package was downloaded from, to the output of the `choco install` and `choco upgrade` commands - see [#1485](https://github.com/chocolatey/choco/issues/1485). -- `choco apikey` - Exit 2 if nothing to do (enhanced exit code) - see [#1759](https://github.com/chocolatey/choco/issues/1759). -- `choco config` - Exit 2 if nothing to do (enhanced exit code) - see [#1760](https://github.com/chocolatey/choco/issues/1760). -- `choco feature` - Exit 2 if nothing to do (enhanced exit code) - see [#1761](https://github.com/chocolatey/choco/issues/1761). -- `choco pin` - Exit 2 if nothing to do (enhanced exit code) - see [#1762](https://github.com/chocolatey/choco/issues/1762). -- `choco source` - Exit 2 if nothing to do (enhanced exit code) - see [#1764](https://github.com/chocolatey/choco/issues/1764). -- `choco upgrade` - Exit 2 if nothing to do (enhanced exit code) - see [#2200](https://github.com/chocolatey/choco/issues/2200). -- Allow upgrading a pinned package without removing the pin beforehand - see [#2050](https://github.com/chocolatey/choco/issues/2050). -- Update `OS_NAME` environment variable to support Windows 11 and Server 2019/2022 - see [#2754](https://github.com/chocolatey/choco/issues/2754). -- Rerunning Install Script after reboot should not be necessary - see [#3327](https://github.com/chocolatey/choco/issues/3327). -- Improve package dependency lookup when an exact version is defined - see [#3433](https://github.com/chocolatey/choco/issues/3433). - -### Documentation - -- Clarify what `--include-programs` option does, in the help output - see [#147](https://github.com/chocolatey/choco/issues/147). -- Fix grammar in the pending reboot warning message - see [#3164](https://github.com/chocolatey/choco/pull/3164). -- Improve the feature `DisableCompatibilityChecks` help description - see [#3296](https://github.com/chocolatey/choco/pull/3296). -- Fix typos and punctuation in `choco feature` and `choco config` error output - see [#3324](https://github.com/chocolatey/choco/pull/3324). -- Clarify `Proxy BypassList` value must be a regular expression, in the help output - see [#3401](https://github.com/chocolatey/choco/issues/3401). -- Remove reference of unused `zip.sh` from README.md file - see [#3402](https://github.com/chocolatey/choco/pull/3402). - - -## 2.2.2 (August 8, 2023) - -> :choco-warning: **WARNING** -> -> There is a bug in Chocolatey CLI v2.2.0 that prevents upgrading if you have a package dependency that only has pre-release versions (or if the package is no longer available on the sources that you have available). If you receive the error `Object reference not set to an instance of an object` please uninstall the package that only has pre-release versions available (or which no longer exists on the sources you have available), upgrade Chocolatey CLI, and re-install the package that was uninstalled. -> -> This [bug has been fixed](https://github.com/chocolatey/choco/issues/3292) in this release of Chocolatey CLI. - -> :choco-warning: **WARNING** -> -> Refer to our [Upgrade Guide](https://docs.chocolatey.org/en-us/guides/upgrading-to-chocolatey-v2-v6) for recommendations before upgrading from 1.x versions to 2.x. - -### Bug Fix - -- Fix - Unable to upgrade a package if a dependency only contains pre-release package versions, or if package no longer exists on available sources - see [#3292](https://github.com/chocolatey/choco/issues/3292). - - -## 2.2.1 (August 3, 2023) - -> :choco-warning: **WARNING** -> -> Chocolatey CLI 2.2.1 was removed from public availability due to a bug identified just prior to the release. - -> :choco-warning: **WARNING** -> -> Refer to our [Upgrade Guide](xref:upgrading-to-chocolatey-v2-v6) for recommendations before upgrading from 1.x versions to 2.x. - -### Bug Fixes - -- Fix - Can't find `choco.exe` after upgrading Chocolatey CLI using the MSI - see [#3286](https://github.com/chocolatey/choco/issues/3286). -- Fix - Unable to do non-elevated operations when `cachelocation` is set to a restricted directory - see [#3291](https://github.com/chocolatey/choco/issues/3291). - -### Dependency Change - -- Update bundled 7zip executables to v23.01 - see [#3285](https://github.com/chocolatey/choco/issues/3285). - - -## 2.2.0 (July 26, 2023) - -> :choco-warning: **WARNING** -> -> Refer to our [Upgrade Guide](xref:upgrading-to-chocolatey-v2-v6) for recommendations before upgrading from 1.x versions to 2.x. - -### Bug Fixes - -- Fix - Upgrading from Chocolatey CLI v2.0.0 to v2.1.0 take a long time to complete when certain other packages are installed - see [#3237](https://github.com/chocolatey/choco/issues/3237). -- Fix - Chocolatey CLI v2.0.0 prompts for credentials when authenticating to a source that is using Windows Authentication - see [#3242](https://github.com/chocolatey/choco/issues/3242). -- Fix - Chocolatey CLI is unable to save HTTP Cache files when running as a non-admin user and the `cachelocation` is set to point at the Chocolatey CLI ProgramData folder - see [#3264](https://github.com/chocolatey/choco/issues/3264). - -### Improvements - -- Remove warning message about "smarter than the average bear" - see [#3186](https://github.com/chocolatey/choco/issues/3186). -- Improve overall execution time when performing the `choco upgrade all` command - see [#3231](https://github.com/chocolatey/choco/issues/3231). -- Expand logging around the exception that is thrown when Chocolatey CLI is unable to communicate with a source - see [#3258](https://github.com/chocolatey/choco/issues/3258). -- Ensure that only Administrators are able to modify files that are stored within the ChocolateyHttpCache folder - see [#3281](https://github.com/chocolatey/choco/issues/3281). - -### Documentation - -- Apply scripting best practices to output which is shown from some Chocolatey CLI validations - see [#3238](https://github.com/chocolatey/choco/pull/3238). -- Improve error message that is shown when defaultPushSource configuration value hasn't been set and no explicit source has been provided - see [#3280](https://github.com/chocolatey/choco/pull/3280). - - -## 2.1.0 (June 29, 2023) - -> :choco-warning: **WARNING** -> -> Refer to our [Upgrade Guide](xref:upgrading-to-chocolatey-v2-v6) for recommendations before upgrading from 1.x versions to 2.x. - -### Bug Fixes - -- Fix - Warning about threshold not shown for multiple sources - see [#3190](https://github.com/chocolatey/choco/issues/3190). -- Fix - System proxy settings (automatically detect settings) are no longer used in v2.0.0 - see [#3181](https://github.com/chocolatey/choco/issues/3181). -- Fix - Incorrect implementation of the `RuleIdEqualityComparer.Equals` method - see [#3182](https://github.com/chocolatey/choco/issues/3182). -- Fix - `choco pin remove -n packagename` removes pin for a different package - see [#3196](https://github.com/chocolatey/choco/issues/3196). -- Fix - Package version normalization is not being applied everywhere - see [#3174](https://github.com/chocolatey/choco/issues/3174). -- Fix - Chocolatey CLI tries to load the licensed environment settings when the licensed extension assembly is not supposed to be loaded - see [#3224](https://github.com/chocolatey/choco/issues/3224). -- Fix - Initial chocolatey.config configuration file is initialized with empty descriptions - see [#3201](https://github.com/chocolatey/choco/issues/3201). -- Fix - Chocolatey CLI does not use the `cachelocation` which is configured within the chocolatey.config file - see [#3225](https://github.com/chocolatey/choco/issues/3225). -- Fix - Checking for presence of Chocolatey license file in tab expansion PowerShell script generates `$error` - see [#3218](https://github.com/chocolatey/choco/issues/3218). - -### Improvements - -- Create PowerShell helper function to read config values - see [#2854](https://github.com/chocolatey/choco/issues/2854). -- Add command to allow purging of cached HTTP queries - see [#3194](https://github.com/chocolatey/choco/issues/3194). -- Provide option for Chocolatey CLI commands to skip cached query results - see [#3193](https://github.com/chocolatey/choco/issues/3193). -- Degraded performance after upgrading to version Chocolatey CLI v2.0.0 - see [#3183](https://github.com/chocolatey/choco/issues/3183). -- `choco search` command does not use previously cached results - see [#3125](https://github.com/chocolatey/choco/issues/3125). - -### Documentation - -- Update contributing documentation to be clearer for newcomers - see [#3108](https://github.com/chocolatey/choco/issues/3108). - - -## 2.1.0-alpha-20230614 (June 14, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey CLI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey CLI **only** works with the alpha version of the Chocolatey Licensed Extension. - -> :choco-info: **NOTE** -> -> The issue that was introduced in the previous alpha release regarding the open ended search query has been addressed in this alpha release. - -> :choco-info: **NOTE** -> -> Before installing this prerelease version, we would recommend that you read through the [Upgrade Instructions](https://docs.chocolatey.org/en-us/guides/upgrading-to-chocolatey-v2-v6) for moving to the major version of Chocolatey CLI. - -### Bug Fixes - -- Fix - Warning about threshold not shown for multiple sources - see [#3190](https://github.com/chocolatey/choco/issues/3190). -- Fix - System proxy settings (automatically detect settings) are no longer used in v2.0.0 - see [#3181](https://github.com/chocolatey/choco/issues/3181). -- Fix - Incorrect implementation of the `RuleIdEqualityComparer.Equals` method - see [#3182](https://github.com/chocolatey/choco/issues/3182). - -### Documentation - -- Update contributing documentation to be clearer for newcomers - see [#3108](https://github.com/chocolatey/choco/issues/3108). - - -## 2.1.0-alpha-20230608 (June 8, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey CLI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey CLI **only** works with the alpha version of the Chocolatey Licensed Extension. - -### Known Issues - -There is a known issue when attempting to do an open ended search query where the Chocolatey Licensed feed is in place. For example, if you run the command `choco search --source chocolatey.licensed` you will get the following error message returned: - -> The specified path, file name, or both are too long. The fully qualified file name must be less than 260 characters, and the directory name must be less than 248 characters. - -A fix has been found for this problem, and will be released in a future alpha release. - -### Bug Fixes - -- Fix - `choco pin remove -n packagename` removes pin for a different package - see [#3196](https://github.com/chocolatey/choco/issues/3196). -- Fix - Package version normalization is not being applied everywhere - see [#3174](https://github.com/chocolatey/choco/issues/3174). - -### Improvements - -- Degraded performance after upgrading to version Chocolatey CLI v2.0.0 - see [#3183](https://github.com/chocolatey/choco/issues/3183). -- `choco search` command does not use previously cached results - see [#3125](https://github.com/chocolatey/choco/issues/3125). - - -## 2.0.0 (May 31, 2023) - -> :choco-warning: **WARNING** -> -> Refer to our [Upgrade Guide](xref:upgrading-to-chocolatey-v2-v6) for recommendations before upgrading from 1.x versions to 2.0.0. - -### Breaking Changes - -- Change behavior of `choco list` to be local only - see [#158](https://github.com/chocolatey/choco/issues/158). -- Prevent usage of leading 0 in package version numbers - see [#1174](https://github.com/chocolatey/choco/issues/1174). -- `choco config list --limit-output` does not limit output as expected - see [#2013](https://github.com/chocolatey/choco/issues/2013). -- Remove `Get-BinRoot` Chocolatey helper function - see [#2623](https://github.com/chocolatey/choco/issues/2623). -- Remove the default push location when uploading/pushing packages - see [#2629](https://github.com/chocolatey/choco/issues/2629). -- Remove deprecated configurations from Config - see [#2630](https://github.com/chocolatey/choco/issues/2630). -- Remove deprecated Chocolatey shims (chocolatey, cinst, clist, cpush, cuninst, cup) - see [#2642](https://github.com/chocolatey/choco/issues/2642). -- Upgrade to target version 4.8 of the .NET Framework - see [#2738](https://github.com/chocolatey/choco/issues/2738). -- Fix spelling mistake in the `extract_binary_file_from_assembly` function - see [#2776](https://github.com/chocolatey/choco/issues/2776). -- Remove side-by-side installs - see [#2788](https://github.com/chocolatey/choco/issues/2788). -- Migrate from Rx-* packages to System.Reactive.* packages - see [#2896](https://github.com/chocolatey/choco/issues/2896). -- Switch to use only the recommended TLS versions without fallback to earlier insecure options - see [#2902](https://github.com/chocolatey/choco/issues/2902). -- Rename or migrate away from custom HashCode class - see [#2909](https://github.com/chocolatey/choco/issues/2909). -- Remove WebPI alternative source - see [#2980](https://github.com/chocolatey/choco/issues/2980). -- Remove the `--remove` option in `apikey` command and replace with `remove` subcommand - see [#2984](https://github.com/chocolatey/choco/issues/2984). -- `choco config list` should only include information about config - see [#2986](https://github.com/chocolatey/choco/issues/2986). -- Disallow passing in a path to a NUPKG file directly when installing/upgrading packages - see [#3008](https://github.com/chocolatey/choco/issues/3008). -- Introduce upper limit when querying for packages and warn when threshold is close to being hit - see [#3014](https://github.com/chocolatey/choco/issues/3014). - -### Bug Fixes - -- Fix - NuGet does not deal with blocking version conflicts from existing installed packages - see [#116](https://github.com/chocolatey/choco/issues/116). -- Fix - NuGet doesn't handle conflicts of versions in an install request when HighestVersion dependency - see [#507](https://github.com/chocolatey/choco/issues/507). -- Fix - Push command does not honor proxy settings - see [#1271](https://github.com/chocolatey/choco/issues/1271). -- Fix - Filenames that contain apostrophes aren't handled correctly when calculating checksums - see [#1590](https://github.com/chocolatey/choco/issues/1590). -- Fix - Chocolatey CLI does not override NuGet proxy with its own - see [#1720](https://github.com/chocolatey/choco/issues/1720). -- Fix - `choco pack` command fails with error on Linux when using file greater than 2 GB - see [#2278](https://github.com/chocolatey/choco/issues/2278). -- Fix - `choco info` command with no package id defined returns 0 packages found rather than provide a warning - see [#2899](https://github.com/chocolatey/choco/issues/2899). - -### Documentation - -- Fix broken URLs in repository README file - see [#2888](https://github.com/chocolatey/choco/pull/2888). -- Update Minimum Windows Server OS to Server 2008 R2 - see [#2903](https://github.com/chocolatey/choco/issues/2903). -- Update package files to reflect current Chocolatey Community Repository moderation requirements - see [#2920](https://github.com/chocolatey/choco/issues/2920). -- Fix typos and spelling errors - see [#2990](https://github.com/chocolatey/choco/pull/2990). - -### Improvements - -- Ability to specify a default source when doing `choco push` - see [#62](https://github.com/chocolatey/choco/issues/62). -- Upgrade to target version 3.1.0 of Chocolatey.NuGet.Client assemblies - see [#508](https://github.com/chocolatey/choco/issues/508). -- Support Semantic Versioning 2.0.0 (semver) - see [#1610](https://github.com/chocolatey/choco/issues/1610). -- `choco info` command doesn't show package URL - see [#1728](https://github.com/chocolatey/choco/issues/1728). -- Ensure that the client version used when querying a repository is the version of the underlying NuGet.Client library - see [#1935](https://github.com/chocolatey/choco/issues/1935). -- Alphabetically sort the output from the `feature` `config` `source` and `apikey` list command - see [#2814](https://github.com/chocolatey/choco/issues/2814). -- Add ability to get status of an individual feature (`choco feature get`) - see [#2815](https://github.com/chocolatey/choco/issues/2815). -- Provide ability to navigate directly to online version of help documentation for a command - see [#2867](https://github.com/chocolatey/choco/issues/2867). -- PowerShell tab completion should only show commands/options for currently installed license - see [#2887](https://github.com/chocolatey/choco/issues/2887). -- Adjust visibility / remove non-interface public methods on CygwinService - see [#3028](https://github.com/chocolatey/choco/issues/3028). -- MSI Build should be present in this repository - see [#3061](https://github.com/chocolatey/choco/issues/3061). -- Chocolatey products should no longer warn about possible errors when upgrading from versions before 1.0.0 - see [#3097](https://github.com/chocolatey/choco/issues/3097). -- Sort list of installed/upgraded packages - see [#3112](https://github.com/chocolatey/choco/issues/3112). - - -## 1.4.0 (May 10, 2023) - -### Bug Fix - -- Fix - When no hook scripts are installed you cannot install/upgrade a package on a system using PowerShell 2 - see [#3088](https://github.com/chocolatey/choco/issues/3088). - -### Improvement - -- Ensure the most recent version of Chocolatey-NuGet.Core package is being used - see [#3150](https://github.com/chocolatey/choco/issues/3150). - - -## 2.0.0-beta-20230426 (April 26, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey CLI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey CLI **only** works with the beta version of the Chocolatey Licensed Extension. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this beta version of Chocolatey CLI we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this beta release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Breaking Change - -- Switch to use only the recommended TLS versions without fallback to earlier insecure options - see [#2902](https://github.com/chocolatey/choco/issues/2902). - -### Bug Fixes - -- Fix - `choco info` command with no package id defined returns 0 packages found rather than provide a warning - see [#2899](https://github.com/chocolatey/choco/issues/2899). -- Fix - Chocolatey CLI does not override NuGet proxy with its own - see [#1720](https://github.com/chocolatey/choco/issues/1720). -- Fix - Ensure that correct `count` query is used when querying oData feeds. - -### Improvements - -- PowerShell tab completion should only show commands/options for currently installed license - see [#2887](https://github.com/chocolatey/choco/issues/2887). -- Alphabetically sort the output from the `feature` `config` `source` and `apikey` list command - see [#2814](https://github.com/chocolatey/choco/issues/2814). -- Add explicit handling for `choco list -li` to provide backwards compatibility - related to [#158](https://github.com/chocolatey/choco/issues/158). -- Add ability to get status of an individual feature (`choco feature get`) - see [#2815](https://github.com/chocolatey/choco/issues/2815). -- Ensure that the client version used when querying a repository is the version of the underlying NuGet.Client library - see [#1935](https://github.com/chocolatey/choco/issues/1935). - - -## 2.0.0-beta-20230412 (April 12, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey CLI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey CLI **only** works with the beta version of the Chocolatey Licensed Extension. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this beta version of Chocolatey CLI we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this beta release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Bug Fixes - -- Fix - Chocolatey CLI does not override NuGet proxy with its own - see [#1720](https://github.com/chocolatey/choco/issues/1720). -- Fix - When no hook scripts are installed you cannot install/upgrade a package on a system using PowerShell 2 - see [#3088](https://github.com/chocolatey/choco/issues/3088). -- Fix - Prevent install/upgrade failure when using multiple sources and one or more of them cannot be reached. - -### Improvements - -- Chocolatey products should no longer warn about possible errors when upgrading from versions before 1.0.0 - see [#3097](https://github.com/chocolatey/choco/issues/3097). -- All the different ways that a proxy can be configured (environment variables, chocolatey.config file, command arguments) have been tested and verified to work as expected. - - -## 2.0.0-beta-20230321 (March 21, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey CLI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey CLI **only** works with the beta version of the Chocolatey Licensed Extension. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this beta version of Chocolatey CLI we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this beta release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Breaking Changes - -In addition to the breaking changes listed in the previous [alpha release](#alpha-20230221-february-21-2023) below, the following changes have been made: - -- `choco config list` should only include information about config - see [#2986](https://github.com/chocolatey/choco/issues/2986). -- Remove the `--remove` option in `choco apikey` command and replace with `remove` subcommand - see [#2984](https://github.com/chocolatey/choco/issues/2984). -- Remove WebPI alternative source - see [#2980](https://github.com/chocolatey/choco/issues/2980). -- Rename or migrate away from custom HashCode class - see [#2909](https://github.com/chocolatey/choco/issues/2909). -- Migrate from Rx-* packages to System.Reactive.* packages - see [#2896](https://github.com/chocolatey/choco/issues/2896). -- Remove side-by-side installs - see [#2788](https://github.com/chocolatey/choco/issues/2788). -- Fix spelling mistake in the extract_binary_file_from_assembly function - see [#2776](https://github.com/chocolatey/choco/issues/2776). -- Remove deprecated Chocolatey shims (`chocolatey`, `cinst`, `clist`, `cpush`, `cuninst`, `cup`) - see [#2642](https://github.com/chocolatey/choco/issues/2642). -- Remove deprecated configurations from Config - see [#2630](https://github.com/chocolatey/choco/issues/2630). -- Remove the default push location when uploading/pushing packages - see [#2629](https://github.com/chocolatey/choco/issues/2629). -- Remove `Get-BinRoot` Chocolatey helper function - see [#2623](https://github.com/chocolatey/choco/issues/2623). -- `choco config list --limit-output` does not limit output as expected - see [#2013](https://github.com/chocolatey/choco/issues/2013). -- Change default behavior of `choco list` to be local only - see [#158](https://github.com/chocolatey/choco/issues/158). - -### Improvements - -- Ability to specify a default source when doing `choco push` - see [#62](https://github.com/chocolatey/choco/issues/62). -- Remove re-instated Chocolatey commands which were added in v1.0.1 - see [#2678](https://github.com/chocolatey/choco/issues/2678). - - -## 1.3.1 (March 14, 2023) - -### Bug Fix - -- Fix - `chocolateyBeforeModify.ps1` does not get called for dependent packages - see [#1092](https://github.com/chocolatey/choco/issues/1092). - -## 2.0.0-alpha-20230307 (March 7, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey CLI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey CLI **only** works with the alpha version of the Chocolatey Licensed Extension. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this alpha version of Chocolatey CLI we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this alpha release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Bug Fixes - -- Fix - Fix `choco search` command that was providing invalid results when using the `--version` option. -- Fix - Fix dependency resolution problems during execution of `choco upgrade` and `choco install`. - -### Improvements - -- Add back support for the `--disable-repository-optimizations` option which was missing in previous alpha releases. -- Improvements made to warnings that are emitted when a dependency fails to be resolved during a `choco upgrade` or `choco install`. - - -## 2.0.0-alpha-20230221 (February 21, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey CLI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey CLI **only** works with the alpha version of the Chocolatey Licensed Extension. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this alpha version of Chocolatey CLI we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this alpha release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Breaking Changes - -In addition to the breaking changes listed in the previous [alpha release](#alpha-20230124-january-24-2023) below, the following changes have been made: - -- Introduce upper limit when querying for packages and warn when threshold is close to being hit - see [3014](https://github.com/chocolatey/choco/issues/3014). -- Disallow passing in a path to a NUPKG file directly when installing/upgrading packages - see [3008](https://github.com/chocolatey/choco/issues/3008). - -### Improvement - -- Add back validation messages after upgrade to NuGet v3+ - see [3000](https://github.com/chocolatey/choco/issues/3000). - -### Documentation - -- Fix typos and spelling errors - see [2990](https://github.com/chocolatey/choco/pull/2990). - - -## [1.3.0](https://github.com/chocolatey/choco/milestone/59?closed=1) (February 15, 2023) - -### Deprecated Features - -- Deprecate WebPI alternative source - see [#2958](https://github.com/chocolatey/choco/issues/2958). -- Deprecate usage of direct path to nupkg or nuspec in `choco install` command - see [#2981](https://github.com/chocolatey/choco/issues/2981). -- Deprecate the `--remove` option in the apikey command - see [#2983](https://github.com/chocolatey/choco/issues/2983). -- Deprecate `choco config list` including output from features/sources/apikeys etc - see [#2985](https://github.com/chocolatey/choco/issues/2985). -- Deprecate unnecessary public methods on CygwinService - see [#3026](https://github.com/chocolatey/choco/issues/3026). - -### Bug Fixes - -- Fix - File not found error when using `--source=cygwin` to install packages - see [#2953](https://github.com/chocolatey/choco/issues/2953). - -## 2.0.0-alpha-20230124 (January 24, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey CLI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey CLI does **NOT** work with the Chocolatey Licensed Extension. It will actually prevent the loading of the Chocolatey Licensed Extension if it is installed. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this alpha version of Chocolatey CLI we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this alpha release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Breaking Changes - -- Upgrade to target version 4.8 of the .NET Framework - see [#2738](https://github.com/chocolatey/choco/issues/2738). -- Prevent usage of leading 0 in package version numbers - see [#1174](https://github.com/chocolatey/choco/issues/1174). - -### Bugs - -- Fix - `choco pack` command fails with error on Linux when using a file greater than 2 GB - see [#2278](https://github.com/chocolatey/choco/issues/2278). -- Fix - Filenames that contain apostrophes aren't handled correctly when calculating checksums - see [#1590](https://github.com/chocolatey/choco/issues/1590). - -### Improvements - -- Upgrade to target version 6.4.0 of NuGet.Client assemblies - see [#508](https://github.com/chocolatey/choco/issues/508). -- Support Semantic Versioning 2.0.0 (semver) - see [#1610](https://github.com/chocolatey/choco/issues/1610). - -### Documentation - -- Fix broken URLs in repository README file - see [#2888](https://github.com/chocolatey/choco/pull/2888). -- Update package files to reflect current CCR moderation requirements - see [#2920](https://github.com/chocolatey/choco/issues/2920). - - -## [1.2.1](https://github.com/chocolatey/choco/milestone/58?closed=1) (December 6, 2022) - -### Bug Fixes - -- Fix - Running `choco new --file` returns "Cannot Combine Path" Error when Chocolatey Licensed Extension is installed and other assemblies are present in the extensions folder - see [#2865](https://github.com/chocolatey/choco/isFix - sues/2865) -- Fix - Selecting `[A] Yes to all` at package script prompt does not work correctly - see [#2872](https://github.com/chocolatey/choco/issues/2872) -- Fix - Attempting to upgrade multiple packages at once causes an error to be thrown about configuration backups - see [#2884](https://github.com/chocolatey/choco/issues/2884) - -## [1.2.0](https://github.com/chocolatey/choco/milestone/54?closed=1) (October 19, 2022) - -> :choco-info: **NOTE** -> -> As part of this release, we have added the functionality to allow officially signed extensions, other than Chocolatey Licensed Extension, to be loaded dynamically. See [#2693](https://github.com/chocolatey/choco/issues/2693). - -### Feature - -- Allow post/pre hooks to run on upgrade/install/uninstall - see [#1185](https://github.com/chocolatey/choco/issues/1185) - -### Deprecated Features - -- Deprecate side-by-side installs - see [#2787](https://github.com/chocolatey/choco/issues/2787) - -### Bug Fixes - -- Fix - Upgrade all reuses overridden package parameters when useRememberedArgumentsForUpgrades feature is turned on - see [#1443](https://github.com/chocolatey/choco/issues/1443) -- Fix - Wrong item set for overriding credentials when using remembered arguments during upgrade - see [#2752](https://github.com/chocolatey/choco/issues/2752) -- Fix - Python alternative source doesn't create arguments correctly due to spelling mistake - see [#2777](https://github.com/chocolatey/choco/issues/2777) -- Fix - Directory permissions not set when installed from PowerShell 7.2.5 - see [#2789](https://github.com/chocolatey/choco/issues/2789) - -### Improvements - -- [Security] Unable to extract files from nupkg when different file name encoding is used - see [#2816](https://github.com/chocolatey/choco/issues/2816) -- Add cmdlet for acquiring paths set in environment variables that should not be used directly - see [#2860](https://github.com/chocolatey/choco/issues/2860) -- Add support for the --pin option on the install and upgrade commands - see [#798](https://github.com/chocolatey/choco/issues/798) -- Packages.config should include all options (including ignorechecksums) - see [#886](https://github.com/chocolatey/choco/issues/886) -- Add option to skip file logging for Zip file extraction in the Get-ChocolateyUnZip and Install-ChocolateyZipPackage cmdlets - see [#1332](https://github.com/chocolatey/choco/issues/1332) -- List parameters in templates - see [#2500](https://github.com/chocolatey/choco/issues/2500) -- ChocolateyTabExpansion.ps1 can cause slow auto-complete in PowerShell - see [#2556](https://github.com/chocolatey/choco/issues/2556) -- Change source type on source runners to be a generic string - see [#2791](https://github.com/chocolatey/choco/issues/2791) -- Remove trailing semicolon in templates and tests - see [#2807](https://github.com/chocolatey/choco/issues/2807) - -### Documentation - -- Minor spelling errors in chocolatey/choco - see [#2465](https://github.com/chocolatey/choco/issues/2465) -- Update brand names - see [#2747](https://github.com/chocolatey/choco/pull/2747) - -## [1.1.0](https://github.com/chocolatey/choco/milestone/53?closed=1) (March 30, 2022) - -### Bug Fixes - -- Fix - Python alternate source does not handle `all` keyword correctly - see [#2540](https://github.com/chocolatey/choco/issues/2540) -- Fix - Incorrect error message is displayed when chocolatey.config becomes corrupt - see [#2525](https://github.com/chocolatey/choco/issues/2525) -- Fix - When running the `choco outdated` command the wrong exit code is shown when there is a pinned package and the `--ignore-pinned` option is being used - see [#1896](https://github.com/chocolatey/choco/issues/1896) -- Fix - Windows PowerShell incorrectly identifies a PowerShell file that is UTF8 encoded with a BOM as being signed if it is a single newline - see [#2663](https://github.com/chocolatey/choco/issues/2663) -- Fix - Unable to install Chocolatey using PowerShell Core - see [#2083](https://github.com/chocolatey/choco/issues/2083) - -### Improvements - -- Support installation checks for incompatible Licensed Extension when running `choco upgrade chocolatey` - see [#2659](https://github.com/chocolatey/choco/issues/2659) -- Support runtime checks for incompatible Chocolatey CLI and Chocolatey Licensed Extension versions - see [#2660](https://github.com/chocolatey/choco/issues/2660) - - When triggered, these checks will output a warning and the beginning of the command execution, and at the end of it. To acknowledge these warnings you can - either pass the `--skip-compatibility-checks` option when executing a command, or you can enable the `DisableCompatibilityChecks` feature using the following - command `choco feature enable --name="'disableCompatibilityChecks'"` -- Include the latest version of 7zip (v21.07) within Chocolatey installation - see [#2650](https://github.com/chocolatey/choco/issues/2650) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [1.0.1](https://github.com/chocolatey/choco/milestone/55?closed=1) (March 24, 2022) - -### Bug Fix - -- Fix - When Chocolatey CLI v1.0.0 attempts to load Chocolatey Licensed Extension versions less than v4.0.0, it halts execution with an unclear and unhelpful error message - see [#2656](https://github.com/chocolatey/choco/issues/2656) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [1.0.0](https://github.com/chocolatey/choco/milestone/50?closed=1) (March 21, 2022) - -> :choco-warning: **WARNING** -> -> If you are using a commercial version of Chocolatey (i.e. you have the chocolatey.extension package installed), you will need to **_first_** upgrade to version v4.0.0 of the [Chocolatey Licensed Extension](xref:licensed-extension-release-notes#march-21-2022). - -### Breaking Changes - -- Remove deprecated Chocolatey commands and shims - see [#2468](https://github.com/chocolatey/choco/issues/2468) -- Remove deprecated Chocolatey helper functions - see [#2469](https://github.com/chocolatey/choco/issues/2469) -- Remove the cpack command alias - see [#89](https://github.com/chocolatey/choco/issues/89) -- Remove the fallback to using old URL for Chocolatey Community Repository when pushing packages - see [#2628](https://github.com/chocolatey/choco/issues/2628) -- Remove deprecated -t argument for the push command - see [#2627](https://github.com/chocolatey/choco/issues/2627) -- Ensure that Chocolatey correctly handles removed features when running the choco feature command - see [#2538](https://github.com/chocolatey/choco/issues/2538) - -### Improvements - -- Update to use version v1.0.0 of shimgen - see [#2602](https://github.com/chocolatey/choco/issues/2602) -- Installation of Chocolatey should add a more descriptive comment when adding Chocolatey tab-completion module to profile - see [#2443](https://github.com/chocolatey/choco/issues/2443) - -### Documentation - -- Update deprecation notice for push command to mention that the default source will be removed in v2.0.0 - see [#2634](https://github.com/chocolatey/choco/issues/2634) -- Mark Chocolatey shims (chocolatey, cinst, clist, cpush, cuninst, cup) as deprecated - see [#2641](https://github.com/chocolatey/choco/issues/2641) -- Mark Get-BinRoot Chocolatey helper function as deprecated - see [#2470](https://github.com/chocolatey/choco/issues/2470) -- Add deprecation notices for all things that are set to change in v2.0.0 - see [#2462](https://github.com/chocolatey/choco/issues/2462) -- Provide better clarity regarding the license terms for using Chocolatey and shimgen - see [#2549](https://github.com/chocolatey/choco/issues/2549), [#2615](https://github.com/chocolatey/choco/issues/2615), and [2614](https://github.com/chocolatey/choco/issues/2614) -- Document the fact that the Source switch doesn't do anything when running the command choco list --lo - see [#2545](https://github.com/chocolatey/choco/issues/2545) -- Update warning that is shown regarding using a trial license of Chocolatey - see [#2407](https://github.com/chocolatey/choco/issues/2407) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.12.1](https://github.com/chocolatey/choco/issues?q=is%3Aclosed+milestone%3A0.12.1) (January 25, 2022) - -### Bug Fixes - -- Fix - Installation of Chocolatey fails when running under "AllSigned" execution policy - see [#2539](https://github.com/chocolatey/choco/issues/2539) -- Fix - Output from "choco template -h" references wrong subcommand in usage statement - see [#2546](https://github.com/chocolatey/choco/issues/2546) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.12.0](https://github.com/chocolatey/choco/issues?q=is%3Aclosed+milestone%3A0.12.0) (January 18, 2022) - -> :choco-warning: **WARNING** -> -> If you use Chocolatey Licensed Extension you will need to install v3.1.0 of Chocolatey Licensed Extension to use all the new functionality that has been added to Chocolatey CLI v0.12.0. - -### Breaking Change - -- Remove ScriptsCheckLastExitCode feature - see [#2522](https://github.com/chocolatey/choco/issues/2522) - -### Features - -- Add command (choco template) to retrieve information about currently installed package templates - see [#449](https://github.com/chocolatey/choco/issues/449) -- Add configuration option for default template name to be used in conjunction with the choco new command - see [#2377](https://github.com/chocolatey/choco/issues/2377) - -### Bug Fixes - -- Fix - Building a package on Linux fails if the description has encoded xml special character(s) - see [#2382](https://github.com/chocolatey/choco/issues/2382) -- Fix - Building a package on Linux fails if nuspec does not have files element - see [#2379](https://github.com/chocolatey/choco/issues/2379) -- Fix - choco pack command fails on non-Windows when the nupkg already exists - see [#2076](https://github.com/chocolatey/choco/issues/2076) -- Fix - Install location is invalid on Linux if the ChocolateyInstall environment variable is not set - see [#2370](https://github.com/chocolatey/choco/issues/2370) -- Fix - During upgrade, removal of old choco.exe does not use absolute path on Linux - see [#2369](https://github.com/chocolatey/choco/issues/2369) -- Fix - Attempting to use ProtectedData.Protect with LocalMachine scope fails when run on non-Windows system as a non-root user - see [#2437](https://github.com/chocolatey/choco/issues/2437) -- Fix - Chocolatey packaging script (chocolateyBeforeModify.ps1) incorrectly running on non-Windows platforms - see [#2510](https://github.com/chocolatey/choco/issues/2510) -- Fix - choco install command ignores install arguments when specifying direct path to nupkg - see [#2089](https://github.com/chocolatey/choco/issues/2089) -- Fix - Deleting NuGet temp folders fails when running on Linux - see [#2383](https://github.com/chocolatey/choco/issues/2383) - -### Improvements - -- Warn about unsupported packages when executing Chocolatey on non-Windows platforms - see [#2481](https://github.com/chocolatey/choco/issues/2481) -- Display install location for purely portable packages - see [#2241](https://github.com/chocolatey/choco/issues/2241) -- Provide more clarity on errors when attempting to push packages to Chocolatey Community Repository - see [#2007](https://github.com/chocolatey/choco/issues/2007) -- Support empty directories within Chocolatey template folder - [#1003](https://github.com/chocolatey/choco/issues/1003) -- Snapshotting of files and config transform has been enabled on non-Windows systems - see [#2450](https://github.com/chocolatey/choco/issues/2450) -- Prevent usage of alternate Chocolatey installation/upgrade sources on non-Windows systems - see [#2424](https://github.com/chocolatey/choco/issues/2424) -- Improve response message regarding moderation times when using choco push command - see [#2298](https://github.com/chocolatey/choco/issues/2298) - -### Documentation - -- Fix outdated bit.ly links in command documentation - see [#2401](https://github.com/chocolatey/choco/issues/2401) -- Update default template regarding building Chocolatey package on non-Windows systems - see [#2384](https://github.com/chocolatey/choco/issues/2384) -- Fix version number used in default template - see [#2381](https://github.com/chocolatey/choco/pull/2381) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.11.3](https://github.com/chocolatey/choco/issues?q=is%3Aclosed+milestone%3A0.11.3) (October 27, 2021) - -### Bug Fixes - -- Fix - Chocolatey fails to load all PowerShell helper cmdlets when attempting to loads modules - see [#2412](https://github.com/chocolatey/choco/issues/2412) -- Fix - Chocolateys PowerShell Installer Module uses non PowerShell 2 compatible syntax - see [#2398](https://github.com/chocolatey/choco/issues/2398) -- Fix - Running Chocolatey CLI with an expired Chocolatey License can result in non-commercial commands failing to run - see [#2289](https://github.com/chocolatey/choco/issues/2289) -- Fix - Installing from packages.config doesn't support installing from other sources (e.g. windowsfeatures, python, etc) - see [#877](https://github.com/chocolatey/choco/issues/877) -- Fix - Quoted InstallLocation in .registry file results in errors when attempting to automatically uninstall application - see [#2336](https://github.com/chocolatey/choco/issues/2336) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.11.2](https://github.com/chocolatey/choco/issues?q=is%3Aclosed+milestone%3A0.11.2) (September 23, 2021) - -### Bug Fix - -- Fix - Setting of Authorization header in Get-WebFile cmdlet does not work - see [#2374](https://github.com/chocolatey/choco/issues/2374) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.11.1](https://github.com/chocolatey/choco/issues?q=is%3Aclosed+milestone%3A0.11.1) (September 2nd, 2021) - -### Bug Fix - -- Fix - Chocolatey Licensed Extension is not loaded into PowerShell process when using v0.11.0 - see [#2340](https://github.com/chocolatey/choco/issues/2340) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.11.0](https://github.com/chocolatey/choco/issues?q=is%3Aclosed+milestone%3A0.11.0) (September 2nd, 2021) - -> :choco-warning: **WARNING** -> -> If you use Chocolatey Licensed Extension you will need to install v2.2.0 of Chocolatey Licensed Extension to use all the new functionality that has been added to Chocolatey CLI v0.11.0. - -### Breaking Changes - -- Disable importing / loading of DLL in the extension folder - see [#2333](https://github.com/chocolatey/choco/issues/2333) -- choco list -e -a returns pre-releases even when --pre is not passed - see [#2304](https://github.com/chocolatey/choco/issues/2304) - -### Bug Fixes - -- Fix - Prevent creation of empty nuget.config in user appdata folder - see [#2233](https://github.com/chocolatey/choco/issues/2233) -- Fix - Upgrade all with remembered arguments changes packages to pre-release - see [#2111](https://github.com/chocolatey/choco/issues/2111) -- Fix - Software applications are being reported as not being managed by Chocolatey when their associated package is installed - see [#2092](https://github.com/chocolatey/choco/issues/2092) -- Fix - Unable to remove API Key with choco apikey command - see [#1889](https://github.com/chocolatey/choco/issues/1889) -- Fix - Not all package versions are returned when running running choco list --all-versions --exact - see [#1843](https://github.com/chocolatey/choco/issues/1843) -- Fix - Upgrade all reuses overridden package parameters when useRememberedArgumentsForUpgrades feature is turned on - see [#1443](https://github.com/chocolatey/choco/issues/1443) -- Fix - choco pack fails when running on Mono when current directory is not the same one that contains the .nuspec being packed - see [#2263](https://github.com/chocolatey/choco/issues/2263) -- Fix - Running choco pack on Mono on Linux will not include any files in .nupkg if there is no files element in the .nuspec - see [#2258](https://github.com/chocolatey/choco/issues/2258) -- Fix - Nuspec files with forward slash creates nested layer of directories when packed on Windows - see [#2166](https://github.com/chocolatey/choco/issues/2166) -- Fix - Prevent loading of Chocolatey GUI Licensed Extension assembly - see [#2078](https://github.com/chocolatey/choco/issues/2078) -- Fix - Working directory always being replaced with configured cache location when using Start-ChocolateyProcessAsAdmin - see [#2051](https://github.com/chocolatey/choco/issues/2051) -- Fix - Temp location can change unexpectedly when using System credentials - see [#2044](https://github.com/chocolatey/choco/issues/2044) -- Fix - Incorrect output regarding package files when package can't be found to be downloaded - see [#1962](https://github.com/chocolatey/choco/issues/1962) - -### Improvements - -- [Security] XML External Entity attack in log4net (CVE-2018-1285) - see [#2266](https://github.com/chocolatey/choco/issues/2266) -- Provide ability to export all currently installed packages to a packages.config file - see [#357](https://github.com/chocolatey/choco/issues/357) -- Provide ability to execute PowerShell script right before installation starts when using Install-ChocolateyPackage - see [#1060](https://github.com/chocolatey/choco/issues/1060) -- Add ChocolateyExitOnRebootDetected feature setting to environment variables for usage within package scripts - see [#1983](https://github.com/chocolatey/choco/issues/1983) -- Only search top level package folders when running the remove pending packages task - see [#1866](https://github.com/chocolatey/choco/issues/1866) -- Change default repository in the chocolatey.config to community.chocolatey.org - see [#2231](https://github.com/chocolatey/choco/issues/2231) -- Support UnzipLocation as an alias to Destination parameter in the Get-ChocolateyUnzip function - see [#2203](https://github.com/chocolatey/choco/issues/2203) -- API - Allow Lets.GetChocolatey to not initialize logging - see [#2124](https://github.com/chocolatey/choco/issues/2124) -- Provide ability to install msp patch files using Install-ChocolateyInstallPackage function - see [#2112](https://github.com/chocolatey/choco/issues/2112) -- Add ability to use authorization headers in the Get-WebFile function - see [#1998](https://github.com/chocolatey/choco/issues/1998) -- Ensure nuspec files generated from the choco new command use UTF-8 without a byte order mark - see [#1364](https://github.com/chocolatey/choco/issues/1364) -- Provide top level help command explaining what commands can be executed - see [#944](https://github.com/chocolatey/choco/issues/944) -- Ensure correct path separator in nuspec files is used on different operating systems - see [#502](https://github.com/chocolatey/choco/issues/502) -- Remove unused variable in uninstall template generated from choco new command - see [#2114](https://github.com/chocolatey/choco/issues/2114) - -### Documentation - -- Clarify the SpecificFolder parameter for helper functions - see [#2190](https://github.com/chocolatey/choco/issues/2190) -- Update deprecation notice to use outdated command when using version command - see [#2048](https://github.com/chocolatey/choco/issues/2048) -- Include information about --version option in choco help documentation - see [#2049](https://github.com/chocolatey/choco/issues/2049) -- Fix examples for Install-ChocolateyPackage function - see [#1899](https://github.com/chocolatey/choco/issues/1899) -- Terminology improvements in choco.exe help output - see [#1861](https://github.com/chocolatey/choco/issues/1861) -- Wrong error message shown when using Get-ChocolateyWebFile and forcex86 - see [#1859](https://github.com/chocolatey/choco/issues/1859) - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.10.15](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.15+is%3Aclosed) (June 3, 2019) - -### Bug Fix - -- Fix - list/search/info - searching with --exact or info results in Object reference not set to an instance of an object - see [#1837](https://github.com/chocolatey/choco/issues/1837) - -## [0.10.14](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.14+is%3Aclosed) (May 30, 2019) - -### Bug Fixes - -- Fix - feature - Turn off Enhanced Exit Codes by Default - see [#1784](https://github.com/chocolatey/choco/issues/1784) -- Fix - Reboot - Pending File Rename Operations check returns true, even after reboot - see [#1768](https://github.com/chocolatey/choco/issues/1768) -- Fix - ".registry.bad" files are created for actually valid registry snapshots - see [#1581](https://github.com/chocolatey/choco/issues/1581) -- Fix - repositories - Azure DevOps NuGet v2 endpoints don't provide metadata in Packages() queries - fails on "Authors is required." - see [#1771](https://github.com/chocolatey/choco/issues/1771) -- Fix - install/upgrade - Chocolatey still fails on failing source repositories - see [#1774](https://github.com/chocolatey/choco/issues/1774) -- Fix - Chocolatey remembers --forceX86 value with subsequent packages - see [#1772](https://github.com/chocolatey/choco/issues/1772) -- Fix - Get-ChocolateyUnzip / Start-ChocolateyProcessAsAdmin - can fail running a process when working directory is a UNC path - see [#1781](https://github.com/chocolatey/choco/issues/1781) -- Fix - Get-UninstallRegistryKey errors when registry keys have bracket characters(`[]`) - see [#1788](https://github.com/chocolatey/choco/issues/1788) -- Fix - push - Fix exception message "There was an internal server error, which might mean the package already exists on a Simple OData Server" / OutOfMemoryException - see [#1786](https://github.com/chocolatey/choco/issues/1786) - -### Improvements - -- info/search/list - apply query optimizations when searching by package id - see [#1831](https://github.com/chocolatey/choco/issues/1831) -- feature - usePackageRepositoryOptimizations to control install/upgrade for repositories that don't handle the newer optimizations well - optimizations break LaGet / NuGet Simple Server (PHP) / PHPNuget / Gemfury - see [#1770](https://github.com/chocolatey/choco/issues/1770) -- install/upgrade/uninstall - allow confirming for remaining installs (aka Yes to All) - see [#53](https://github.com/chocolatey/choco/issues/53) -- Config: Setting to exempt packages from upgrade all - see [#1433](https://github.com/chocolatey/choco/issues/1433) -- Support ARM64 Win32 32bit emulation - see [#1800](https://github.com/chocolatey/choco/issues/1800) -- outdated - Add --pre to outdated command - see [#1804](https://github.com/chocolatey/choco/issues/1804) -- Update tab completion options - see [#1834](https://github.com/chocolatey/choco/issues/1834) - -## [0.10.13](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.13+is%3Aclosed) - (March 15, 2019) - -### Bug Fix - -- Fix - Licensed - Licensed code failing when using licensed PowerShell functions - see [#1767](https://github.com/chocolatey/choco/issues/1767) - -## [0.10.12](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.12+is%3Aclosed) - (March 14, 2019) - -We are pretty excited to finally share a new Chocolatey release! And this release won't disappoint. Loads of bug fixes, enhanced exit codes for search, list, info and outdated when results are returned versus nothing being returned, and some really nice improvements. - -Perhaps the biggest addition this release is the ability to halt installation if a reboot is detected ([#1038](https://github.com/chocolatey/choco/issues/1038)). Once you turn this feature on, if you are installing some packages and somewhere in the middle of that there is a need for a reboot, Chocolatey will stop and exit with either exit code 350 (pending reboot prior to anything) or 1604 (install incomplete), indicating a reboot is needed to continue. It won't reboot for you, as it is just a package manager - but it will stop execution so nothing that may error on install is attemtped. You'll need to opt into this feature, so see [#1038](https://github.com/chocolatey/choco/issues/1038) for details. - -If you've long hated the default console colors, we've spent quite a bit of time detecting the background console color and adjusting the colorization output of Chocolatey for this release ([#1131](https://github.com/chocolatey/choco/issues/1131)). You might give that a whirl and see if you can turn back on console colors for good. - -We've added the ability to validate the configuration and system state at a global level ([#1746](https://github.com/chocolatey/choco/issues/1746)). It's early, but expect that we'll do a lot more to really provide good experiences in this area. - -A bug that is worth noting as fixed is having choco exit when a source fails instead of ignoring it ([#612](https://github.com/chocolatey/choco/issues/612)). This is now fixed! - -The last thing worth noting in the summary is Enhanced Exit Codes, or providing more intentional exit codes that mean something instead of just 0 or 1 ([#1758](https://github.com/chocolatey/choco/issues/1758)). In this release, outdated and search commands will have additional exit codes that mean something. This is noted in the next section, so please read over and see how to shut off this behavior if you see it breaking any integration you might be using (including your own scripts). - -### Breaking Changes - -- outdated - Exit 2 when there are packages out of date - see [#1602](https://github.com/chocolatey/choco/issues/1602) -- search/list/info - Exit 2 when no results are returned - see [#1724](https://github.com/chocolatey/choco/issues/1724) - -We've listed these as breaking changes as it may affect tools that are integrating with Chocolatey and interpreting the output of the exit code. In these cases, it would likely temporarily break those tools until they've had a chance to release new versions of their tools. If you run into this, you simply need to turn off the feature "useEnhancedExitCodes". That is as simple as `choco feature disable --name="'useEnhancedExitCodes'"` ([#1758](https://github.com/chocolatey/choco/issues/1758)). - -### Features - -- Exit when reboot is detected - w/350 for pending & w/1604 on dependency package requiring reboot - see [#1038](https://github.com/chocolatey/choco/issues/1038) - -### Bug Fixes - -- [Security] Fix - upgrade - remove automation scripts prior to upgrade even if changed - see [#1689](https://github.com/chocolatey/choco/issues/1689) -- [Security] Fix - scripts - Digitally sign the init.ps1 PowerShell file as well - see [#1665](https://github.com/chocolatey/choco/issues/1665) -- Fix - When a source fails, choco exits instead of moving to next source - see [#612](https://github.com/chocolatey/choco/issues/612) -- Fix - Upgrade all reuses overridden package parameters when useRememberedArgumentsForUpgrades feature is turned on - see [#1443](https://github.com/chocolatey/choco/issues/1443) -- Fix - Passing `--execution-timeout=0` doesn't override the default execution timeout in the configuration - see [#1747](https://github.com/chocolatey/choco/issues/1747) -- Fix - ChocolateyLastPathUpdate environment variable stores date as locale-specific - see [#1604](https://github.com/chocolatey/choco/issues/1604) -- [POSH Host] Fix - install/upgrade/uninstall - PowerShell host should exit with 1 instead of -1 if there is a package error - see [#1734](https://github.com/chocolatey/choco/issues/1734) -- Fix - Logging - warnings for ".registry.bad." files are emitted with "-r" switch - see [#1580](https://github.com/chocolatey/choco/issues/1580) -- Fix - Logging - ".registry.bad" files are created for actually valid registry snapshots - see [#1581](https://github.com/chocolatey/choco/issues/1746) -- Fix - list/search - Listing local packages fails if no sources are enabled - see [#661](https://github.com/chocolatey/choco/issues/661) -- Fix - uninstall - Object reference exception when there are no sources - see [#1584](https://github.com/chocolatey/choco/issues/1584) -- Fix - Logging - self-service errors attempting to write to the config when using Chocolatey GUI - see [#1649](https://github.com/chocolatey/choco/issues/1649) -- Fix - source list - running with -r fails to escape pipe (|) char - see [#1614](https://github.com/chocolatey/choco/issues/1614) -- Fix - source add - Adding a source allows an empty url - see [#1582](https://github.com/chocolatey/choco/issues/1582) -- Fix - Get-ChocolateyWebFile - Ensure PSVersionTable is used for PowerShell Version - see [#1623](https://github.com/chocolatey/choco/issues/1623) -- Fix - Install-ChocolateyShortcut - Don't create a folder if environment variable is used - see [#1687](https://github.com/chocolatey/choco/issues/1687) -- Fix - `choco --version` includes warnings, breaks version parsing - see [#1562](https://github.com/chocolatey/choco/issues/1562) -- Fix - Uninstall-ChocolateyZipPackage failing with Path error - see [#1550](https://github.com/chocolatey/choco/issues/1550) -- Fix - Uninstall-ChocolateyZipPackage fails from null passed to Test-Path - see [#1546](https://github.com/chocolatey/choco/issues/1546) -- Fix - Get-ChocolateyUnzip - Ensure 7z cmd window is hidden - see [#1642](https://github.com/chocolatey/choco/issues/1642) -- [API] Fix - Resolve assemblies globally without locking - see [#1735](https://github.com/chocolatey/choco/issues/1735) - -### Improvements - -- [Security] tools - Update 7z to 18.06 - see [#1704](https://github.com/chocolatey/choco/issues/1704) -- [Security] Refreshenv script leaves temporary file behind - see [#1549](https://github.com/chocolatey/choco/issues/1549) -- Control enhanced exit codes with a feature switch - see [#1758](https://github.com/chocolatey/choco/issues/1758) -- Logging - better default colors - see [#1131](https://github.com/chocolatey/choco/issues/1131) -- Validate config / system state across everything - see [#1746](https://github.com/chocolatey/choco/issues/1746) -- upgrade - switch for not installing if not installed - see [#1646](https://github.com/chocolatey/choco/issues/1646) -- outdated - improve performance of `choco outdated` - see [#1397](https://github.com/chocolatey/choco/issues/1397) -- search/list - Add alias "find" for search - see [#1744](https://github.com/chocolatey/choco/issues/1744) -- apikey - Enable removal of API key via CLI - see [#1301](https://github.com/chocolatey/choco/issues/1301) -- Logging - Choco --log-file option should create log files relative to current directory - see [#1603](https://github.com/chocolatey/choco/issues/1603) -- Logging - Don't suggest installing separate "checksum" tool - see [#981](https://github.com/chocolatey/choco/issues/981) -- template - Add notes to uninstaller file string on how to correctly parse the value from the registry - see [#1644](https://github.com/chocolatey/choco/issues/1644) -- Pro/Business - license - If license is found in top-level folder or named wrong, choco should warn - see [#1503](https://github.com/chocolatey/choco/issues/1503) -- [API] Allow verifying DI Container in release build - see [#1738](https://github.com/chocolatey/choco/issues/1738) -- [API] ability to get consistent hash of ConfigFileSettings class - see [#1612](https://github.com/chocolatey/choco/issues/1612) - -## [0.10.11](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.11+is%3Aclosed) (May 4, 2018) - -### Bug Fixes - -- Fix - AutoUninstaller - Captures registry snapshot escaping quotes - unable to find path for uninstall - see [#1540](https://github.com/chocolatey/choco/issues/1540) -- Fix - Installation/Setup - Use of Write-Host in Install-ChocolateyPath.ps1 prevents non-interactive installation of Chocolatey itself - see [#1560](https://github.com/chocolatey/choco/issues/1560) -- Fix - Logging - GUID in software name: "Chocolatey had an error formatting string" - see [#1543](https://github.com/chocolatey/choco/issues/1543) - -### Improvements - -- [Security] RAR Extraction with older 7zip uses uninitialized memory (CVE-2018-10115) - see [#1557](https://github.com/chocolatey/choco/issues/1557) -- Tab Completion - Modify profile if file exists but is empty - see [#991](https://github.com/chocolatey/choco/issues/991) - -## [0.10.10](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.10+is%3Aclosed) (April 12, 2018) - -### Bug Fixes - -- Fix - Installing Chocolatey 0.10.9 results in an exit code of 1 - see [#1529](https://github.com/chocolatey/choco/issues/1529) -- Fix - Proxy bypass list with "*" will return regex quantifier parsing errors - see [#1532](https://github.com/chocolatey/choco/issues/1532) -- Fix - NuGet cache folders - choco should always attempt to remove and should find in the cacheLocation when set - see [#1527](https://github.com/chocolatey/choco/issues/1527) - -### Improvement - -- Logging - Exclusive File Lock on Non-Essential Logs - see [#1531](https://github.com/chocolatey/choco/issues/1531) - -## [0.10.9](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.9+is%3Aclosed) (March 25, 2018) - -The vendored 7Zip had a couple of security findings that necessitated a release. There is also a lot of goodness going into this release as well. We've fixed XDT transforms not to keep extra data around (requiring manual fixes). We've resolved some issues surrounding compatibility with Get-PackageParameters in the chocolatey-core.extension package and what's now built into Chocolatey. That should now work appropriately, and the built-in method should be preferred, so if you are using `--package-parameters-sensitive`, those will be added as well when you do have the chocolatey-core.extension package also installed. - -We've also brought in the long desired logging with no colorization. You can set that as a switch or globally with a feature flipper. With outdated/upgrade, you can now ignore unfound packages along with already skipping pinned packages. That will help you reduce your output to only the things it finds upgrades for that can be upgraded. - -### Bug Fixes - -- [Security] Fix - Pro/Business - Logging - Get-PackageParameters should not log sensitive params - see [#1460](https://github.com/chocolatey/choco/issues/1460) -- Fix - XDT transform causes xml file to have extra data in it (unusable until manually fixed) - see [#1482](https://github.com/chocolatey/choco/issues/1482) -- Fix - Escape package registry information to reduce unreadable files - see [#1505](https://github.com/chocolatey/choco/issues/1505) -- Fix - Uninstall-ChocolateyZipPackage is unable to find zip contents file - see [#1415](https://github.com/chocolatey/choco/issues/1415) -- Fix - Get-PackageParameters - Resolve differences between chocolatey.core-extension and built-in method - see [#1490](https://github.com/chocolatey/choco/issues/1490) -- Fix - Get-PackageParameters - force built-in method to be preferred over chocolatey-core.extension method - see [#1476](https://github.com/chocolatey/choco/issues/1476) -- Fix - Get-PackageParameters should handle urls - see [#1459](https://github.com/chocolatey/choco/issues/1459) -- Fix - Setting output directory with proper quoting can result in "The given path's format is not supported." - see [#1517](https://github.com/chocolatey/choco/issues/1517) -- Fix - Logging - PowerShell script contents logging should not error if they have contents mistaken for log formatting - see [#1489](https://github.com/chocolatey/choco/issues/1489) -- Fix - Incorrect documentation for Install-ChocolateyInstallPackage - see [#1416](https://github.com/chocolatey/choco/issues/1416) -- [API] Fix - Logging - Loggers should always be checked for initialization - see [#1447](https://github.com/chocolatey/choco/issues/1447) -- Fix - Pro/Business - Expired licenses should not cause Chocolatey errors - see [#1500](https://github.com/chocolatey/choco/issues/1500) - -### Improvements - -- [Security] RAR extraction with older 7zip can cause memory corruption (CVE-2018-5996) / ZIP Shrink vulnerability (CVE-2017-17969) - see [#1478](https://github.com/chocolatey/choco/issues/1478) -- Provide friendly error messages on well-known exit codes - see [#1526](https://github.com/chocolatey/choco/issues/1526) -- Capture password securely during validation when only the user name has been provided - see [#1524](https://github.com/chocolatey/choco/issues/1524) -- Outdated/Upgrade - Option/feature to ignore unfound packages - see [#1398](https://github.com/chocolatey/choco/issues/1398) -- Installation/Setup: run choco once to initialize the config file - see [#1401](https://github.com/chocolatey/choco/issues/1401) -- Logging - Log access denied for config file to log file only - see [#1445](https://github.com/chocolatey/choco/issues/1445) -- Ability to pick x64/x86 runtime binaries for shimming by architecture without needing PowerShell scripts - see [#1365](https://github.com/chocolatey/choco/issues/1365) -- Logging - Add '--no-color' as a global option and 'logWithoutColor' feature - see [#100](https://github.com/chocolatey/choco/issues/100) -- Reset colors after abnormal exit - see [#474](https://github.com/chocolatey/choco/issues/474) -- [API] Logging - Set logging levels debug/verbose/trace - see [#1448](https://github.com/chocolatey/choco/issues/1448) -- [API] Logging - Sync already logged items when setting custom logging - see [#1446](https://github.com/chocolatey/choco/issues/1446) -- [API] Fix - Ensure one instantiation of GetChocolatey at a time - see [#1400](https://github.com/chocolatey/choco/issues/1400) -- Pro/Business - Uninstall - Keep stored package information by default - see [#1399](https://github.com/chocolatey/choco/issues/1399) -- Pro/Business - Logging - See licensing logging output - see [#1488](https://github.com/chocolatey/choco/issues/1488) - -## [0.10.8](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.8+is%3Aclosed) (August 30, 2017) - -With this release, Package Parameters are fully supported from both the user side and the packaging side. Check out [the documentation](https://docs.chocolatey.org/en-us/create/functions/get-packageparameters) and check out the [walkthrough](xref:parse-package-parameters) on how to use package parameters in your packaging. Note if you are pushing packages to the community repository, you must continue to take a dependency on the `chocolatey-core.extension` as a polyfill for older versions until at least six months after a new feature is released. - -What you can do with logging has greatly increased your ability to have more power over how it works and deeper output to determine errors (we've expanded `--trace` [#1379](https://github.com/chocolatey/choco/issues/1379)). This release also gives packagers and users more power when working with the AutoUninstaller - opt-out ([#1257](https://github.com/chocolatey/choco/issues/1257)) and passing arguments to the uninstaller ([#1133](https://github.com/chocolatey/choco/issues/1133)). - -Another noteworthy addition is the ability to pass custom properties to Choco like you would do with `nuget pack`, allowing better integration with packages you manage in Visual Studio ([#1313](https://github.com/chocolatey/choco/issues/1313)). - -### Feature - -- Function - Get-PackageParameters - see [#1393](https://github.com/chocolatey/choco/issues/1393) - -### Bug Fixes - -- Fix - "Value cannot be null" running choco outdated - see [#1383](https://github.com/chocolatey/choco/issues/1383) -- Fix - Package parameters are ignored on when install directly points to nupkg/nuspec - see [#1155](https://github.com/chocolatey/choco/issues/1155) -- Fix - Logging - log4net Logger location (the code location logging) is incorrect - see [#1377](https://github.com/chocolatey/choco/issues/1377) -- [API] Fix - GetConfiguration() sets the configuration for other calls - see [#1347](https://github.com/chocolatey/choco/issues/1347) -- [API] Fix - Pro/Business - Self-Service information not returned for sources - see [#1394](https://github.com/chocolatey/choco/issues/1394) -- [API] Fix - Config output is being set to Regular Output - see [#1396](https://github.com/chocolatey/choco/issues/1396) - -### Improvements - -- [Security][POSH Host] Implement Read-Host -AsSecureString- see [#1335](https://github.com/chocolatey/choco/issues/1335) -- AutoUninstaller - Opt-out from packages - see [#1257](https://github.com/chocolatey/choco/issues/1257) -- AutoUninstaller - Use Uninstall Arguments and Override Arguments if provided - see [#1133](https://github.com/chocolatey/choco/issues/1133) -- pack - Pass arbitrary properties like nuget pack - see [#1313](https://github.com/chocolatey/choco/issues/1313) -- list - Sub-command should not require admin access (and not prompt) - see [#1353](https://github.com/chocolatey/choco/issues/1353) -- new - Package Templates - Do not treat binaries in template as text files - see [#1385](https://github.com/chocolatey/choco/issues/1385) -- new - Package Templates - Add more helpful items, like a todo list to the default template - see [#1386](https://github.com/chocolatey/choco/issues/1386) -- Document how to pass multiple sources on CLI - see [#1331](https://github.com/chocolatey/choco/issues/1331) -- Logging - Trace output should provide deep logging information - see [#1379](https://github.com/chocolatey/choco/issues/1379) -- Logging - Allow external log4net config file - see [#1378](https://github.com/chocolatey/choco/issues/1378) -- Logging - Allow capturing output to an additional log file - see [#1376](https://github.com/chocolatey/choco/issues/1376) -- [API] Make log4net dependency less restrictive - see [#1395](https://github.com/chocolatey/choco/issues/1395) -- Pro/Business - source/list - Support for Admin Only Sources - Limit non-admin list to self service only - see [#1265](https://github.com/chocolatey/choco/issues/1265) - -## [0.10.7](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.7+is%3Aclosed) (June 8, 2017) - -### Breaking Change - -- Set requested execution level back to asInvoker while determining more advanced elevated scenarios - see [#1324](https://github.com/chocolatey/choco/issues/1324) - - After much deliberation with the community, we're moving execution policy back to the default of `asInvoker` to make it work like it did prior to 0.10.4. However we are leaving it open for you to change it to whatever execution level you want by keeping the manifest external from choco.exe. We will be looking more at advanced scenarios - the discussion is at [#1307](https://github.com/chocolatey/choco/issues/1307). If you don't have a GitHub account, feel free to start a thread on the mailing list (and if you are a customer, you have private channels to voice your opinions on this change). - - Moving to "asInvoker" means that Chocolatey will not ask for elevated privileges prior to execution, so you will need to remember to do that yourself. If you go to `$env:ChocolateyInstall`, you will find `choco.exe.manifest`, and you have freedom to adjust the execution level as you see fit. There is one catch, you will need to do it on every install/upgrade of Chocolatey until [#1206](https://github.com/chocolatey/choco/issues/1206) is implemented. - -### Bug Fixes - -- Fix - Add file/file64 not as aliases, but use them to set url/url64 if empty - see [#1323](https://github.com/chocolatey/choco/issues/1323) -- Fix - Automatic Uninstaller doesn't split multiple paths - see [#1327](https://github.com/chocolatey/choco/issues/1327) -- Fix - choco list / search / info - fails with local directory source - see [#1325](https://github.com/chocolatey/choco/issues/1325) -- Fix - When version is four digits, Chocolatey version heading is not shown - see [#1326](https://github.com/chocolatey/choco/issues/1326) -- Fix - search / list - page/page-size not honored for exact search in 0.10.6 - see [#1322](https://github.com/chocolatey/choco/issues/1322) -- Fix - Deserializing failures on package info files should not fail the choco run - see [#1328](https://github.com/chocolatey/choco/issues/1328) - -### Improvements - -- Use `$packageArgs` in default template for uninstall script - see [#1330](https://github.com/chocolatey/choco/issues/1330) - -## [0.10.6.1](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.6.1+is%3Aclosed) (June 3, 2017) - -### Bug Fixes - -- Fix - shimgen fails with unrecognized option: '/errorendlocation' in .NET 4.0 only environments - see [#1321](https://github.com/chocolatey/choco/issues/1321) -- Fix - Do not fail extracting resources at runtime - see [#1318](https://github.com/chocolatey/choco/issues/1318) -- Fix - Silently fail when deleting choco.exe.old - see [#1319](https://github.com/chocolatey/choco/issues/1319) - -## [0.10.6](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.6+is%3Aclosed) (June 1, 2017) - -This release includes fixes and adjustments to the API to make it more usable. Search / List has also been improved with the data that it returns when verbose/detailed, along with info always returning a package with information instead of erroring sometimes. The search results from the community package repository now match what you see on the website. - -### Bug Fixes - -- Fix - choco.exe.manifest is ignored because it is extracted AFTER first choco.exe access - see [#1292](https://github.com/chocolatey/choco/issues/1292) -- Fix - Chocolatey config changes in 0.10.4+ - The process cannot access the file because it is being used by another process - see [#1241](https://github.com/chocolatey/choco/issues/1241) -- Fix - PowerShell sees authenticode hash as changed in scripts that are UTF8 (w/out BOM) that contain unicode characters - see [#1225](https://github.com/chocolatey/choco/issues/1225) -- Fix - Chocolatey timed out immediately when execution timeout was infinite (0) - see [#1224](https://github.com/chocolatey/choco/issues/1224) -- Fix - Multiple authenticated sources with same base url fail when authentication is different - see [#1248](https://github.com/chocolatey/choco/issues/1248) -- Fix - choco list / search / info - Some packages can't be found - see [#1004](https://github.com/chocolatey/choco/issues/1004) -- Fix - chocolatey.config gets corrupted when multiple processes access simultaneously - see [#1258](https://github.com/chocolatey/choco/issues/1258) -- Fix - Update ShimGen to 0.8.x to address some issues - see [#1243](https://github.com/chocolatey/choco/issues/1243) -- Fix - AutoUninstaller should skip uninstall keys if they are empty - see [#1315](https://github.com/chocolatey/choco/issues/1315) -- Fix - Trace logging should only occur on when trace is enabled - see [#1309](https://github.com/chocolatey/choco/issues/1309) -- Fix - RefreshEnv.cmd doesn't set the correct PATH - see [#1227](https://github.com/chocolatey/choco/issues/1227) -- Fix - choco new generates uninstall template with wrong use of registry key variable - see [#1304](https://github.com/chocolatey/choco/issues/1304) -- [API] Fix- chocolatey.lib nuget package has incorrect documentation xml - see [#1247](https://github.com/chocolatey/choco/issues/1247) -- [API] Fix - Chocolatey file cache still adds a 'chocolatey' directory on each install - see [#1231](https://github.com/chocolatey/choco/issues/1231) -- [API] Fix - List and Count should implement similar functionality as run - see [#1298](https://github.com/chocolatey/choco/issues/1298) -- Pro/Business - [API] Fix - Ensure DLL can work with licensed code - see [#1287](https://github.com/chocolatey/choco/issues/1287) - -### Improvements - -- Default package push url now uses push subdomain - see [#1285](https://github.com/chocolatey/choco/issues/1285) -- Report process id in the log files - see [#1239](https://github.com/chocolatey/choco/issues/1239) -- choco info / list / search - Include summary on detailed view - see [#1253](https://github.com/chocolatey/choco/issues/1253) -- choco info / list /search - Include release notes on detailed view - see [#1263](https://github.com/chocolatey/choco/issues/1263) -- choco list / search - Option to list packages only by name - see [#1237](https://github.com/chocolatey/choco/issues/1237) -- choco list / search - Allow sorting package results by relevance - see [#1101](https://github.com/chocolatey/choco/issues/1101) -- choco list / search - Search by tags only - see [#1033](https://github.com/chocolatey/choco/issues/1033) -- choco outdated - Option to leave out pinned packages - see [#994](https://github.com/chocolatey/choco/issues/994) -- Install-ChocolateyPackage and other functions should alias File/File64 - see [#1284](https://github.com/chocolatey/choco/issues/1284) -- Install-ChocolateyPowerShellCommand should alias File/FileFullPath for PsFileFullPath - see [#1311](https://github.com/chocolatey/choco/issues/1311) -- Logging - capture more information about a user (user name, domain, remote?, system?) - see [#615](https://github.com/chocolatey/choco/issues/615) -- Stop saying "0 packages failed." - see [#1259](https://github.com/chocolatey/choco/issues/1259) -- [API] provide a way to see ChocolateyConfiguration - see [#1267](https://github.com/chocolatey/choco/issues/1267) -- [API] Attempt to get ChocolateyInstall environment variable prior to extraction - see [#1297](https://github.com/chocolatey/choco/issues/1297) -- [API] Expose Container directly - see [#1294](https://github.com/chocolatey/choco/issues/1294) -- Pro/Business - Support for Package Audit (who installed packages) - see [#1238](https://github.com/chocolatey/choco/issues/1238) -- Pro/Business - [API] Ensure configuration retains base info between uses - see [#1296](https://github.com/chocolatey/choco/issues/1296) - -## [0.10.5](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.5+is%3Aclosed) (March 30, 2017) - -### Bug Fix - -- Fix - Start-ChocolateyProcessAsAdmin errors when running PowerShell scripts - see [#1220](https://github.com/chocolatey/choco/issues/1220) - -### Improvement - -- Show machine readable output with `choco outdated -r` - see [#1222](https://github.com/chocolatey/choco/issues/1222) - -## [0.10.4](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.4+is%3Aclosed) (March 30, 2017) - -We're dubbing this the "10-4 good buddy" release. We've added some major functionality and fixes we think you are going to find top notch - dare we say as smooth as really expensive chocolate? A lot of work for this release has been provided by the community. Remember that Chocolatey is only as good as the support that comes from the community! Be sure to thank other community members for the awesome that is Chocolatey and Chocolatey 10-4. We've closed over 30 bugs and added over 40 enhancements (75 tickets in total)! - -Proxy support just got some major enhancements with the ability to not only [specify proxy information at runtime](https://github.com/chocolatey/choco/issues/1173), but also to [set bypass lists and bypassing on local connections](https://github.com/chocolatey/choco/issues/1165) and [configure source repositories to bypass proxies](https://github.com/chocolatey/choco/issues/262). A major issue with [changing command execution timeout](https://github.com/chocolatey/choco/issues/1059) was just fixed. And there used to be a tiny chance you might [corrupt the choco config when running multiple choco processes](https://github.com/chocolatey/choco/issues/1047) -but now that is much better handled. - -We've also made [package itself display download progress](https://github.com/chocolatey/choco/issues/1134), which is great when software binaries are embedded in packages. For you folks looking to remove any progress (like when using Vagrant), now you can use [`--no-progress`](https://github.com/chocolatey/choco/issues/917). When NuGet.Core has issues, those issues will have more visibility into why things are failing without needing a debugging log. Speaking of some extreme visibility, see network traffic with [`--trace`](https://github.com/chocolatey/choco/issues/1182). - -We've got a few possible breaking changes that could affect you, see what we've written about them below. - -This also marks the first release that uses the [Chocolatey Software digital certificate for signing](https://github.com/chocolatey/choco/issues/1214) instead of the RealDimensions Software, LLC certificate. - -Another major feature released in preview is [using remembered arguments on upgrade](https://github.com/chocolatey/choco/issues/797). This is in preview in 0.10.4 and will be turned to 'on' automatically in a future release. We are going to be continually making it better and won't turn it on by default until it is ready. If you want to turn it on and start using it, once you have 0.10.4 installed, run `choco feature enable --name useRememberedArgumentsForUpgrades`. You can also do this per command with `--use-remembered-arguments`. You can also turn it off per command with `--ignore-remembered-arguments`. We've also really described a lot of important considerations and thoughts related to using this so there are no surprises. Please do read the issue notes at length if you plan to use this feature to reduce confusion. - -### Breaking Changes - -- Run with highestAvailable Execution Level by default - see [#1054](https://github.com/chocolatey/choco/issues/1054) - - One longstanding request with Chocolatey was to have it always request admin privileges before running. This has been a hope that it would cut down on the accidental runs of Chocolatey in a command shell that is not elevated and needing to open one that is elevated. This UAC (User account control) setting is handled by something called an application manifest (app.manifest). We had it set to "asInvoker", or run with the context of the user that ran the command. We've moved this to "highestAvailable", which means if you are a non-admin, it will just run under your context, but if you are an admin in a non-elevated shell, it will ask for elevated permissions to run. There is also "requireAdministrator", which locks execution down to administrators only. - - Moving to "highestAvailable" allows for that asking of privileges that you are used to, up front before it runs. However one additional thing we did here was give you more control over this setting now. We used to embed the app manifest into choco.exe. We now set it next to choco.exe (base install under `$env:ChocolateyInstall`, you will find `choco.exe.manifest`) so you have more freedom to adjust those execution levels as you see fit. There is one catch, you will need to do it on every install/upgrade of Chocolatey until [#1206](https://github.com/chocolatey/choco/issues/1206) is implemented. - -- When a prerelease is installed, it should upgrade to latest prerelease unless excluded - typically seen in choco upgrade all - see [#686](https://github.com/chocolatey/choco/issues/686) - - When you run `choco upgrade all`, it never catches the prereleases. However if you run `choco upgrade all --pre`, it may upgrade some of your stable installs to prereleases. Neither of these situations are desirable. So by default, we've made it so that `choco upgrade all` just does the right thing, which is to upgrade your stable releases to the latest stable release and your prerelease packages will upgrade to the absolute latest available, whether that be stable or prerelease. If you need to change the behavior back to the old way for upgrade all, simply add the `--exclude-prerelease` option. - -- Fix - Passing Allow Downgrade To upgrade against a prerelease may downgrade it to last stable version - see [#1212](https://github.com/chocolatey/choco/issues/1212) - - This is a bug fix that was allowing a prerelease to be downgraded accidentally to the last stable version if you ran `choco upgrade somepackage --allow-downgrade` without a particular version and without `--pre`. Now while this would be less affected with #686 above, it could still happen. It's a bug. The only reason this was marked as breaking change is that someone could be depending on the buggy behavior. So heads up, this bug is now fixed. If you are attempting to downgrade, make sure you specify the version you want it to go down to. - -### Features - -- [Security][Preview] Use Remembered Arguments for a Package During Upgrades - You must opt in for this to work - see [#797](https://github.com/chocolatey/choco/issues/797) -- Show download progress for the packages themselves - see [#1134](https://github.com/chocolatey/choco/issues/1134) -- Set Explicit Proxy Bypass List / Bypass On Local - see [#1165](https://github.com/chocolatey/choco/issues/1165) -- Option/feature to stop installation when a package fails - see [#1151](https://github.com/chocolatey/choco/issues/1151) -- Add File64 to Install-ChocolateyInstallPackage and Get-ChocolateyUnzip - see [#1187](https://github.com/chocolatey/choco/issues/1187) - -### Bug Fixes - -- [Security] Fix - PowerShell sees authenticode hash as changed in scripts that were signed with Unix Line Endings (`LF`) - unable to use `AllSigned` - see [#1203](https://github.com/chocolatey/choco/issues/1203) -- [Security] Fix - chocolatey setup - Use https for downloading .NET Framework 4x if not installed - see [#1112](https://github.com/chocolatey/choco/issues/1112) -- Fix - chocolatey.config gets corrupted when multiple processes access simultaneously - see [#1047](https://github.com/chocolatey/choco/issues/1047) -- Fix - "commandExecutionTimeoutSeconds" always reverts to 2700 when deprecated config setting is 0 - see [#1059](https://github.com/chocolatey/choco/issues/1059) -- Fix - Allow Chocolatey version check with FIPS - see [#1193](https://github.com/chocolatey/choco/issues/1193) -- Fix - Chocolatey doesn't always decompress downloads appropriately (support automatic decompression) - see [#1056](https://github.com/chocolatey/choco/issues/1056) -- Fix - Load built-in Chocolatey functions, then load extensions - see [#1200](https://github.com/chocolatey/choco/issues/1200) -- Fix - Use provided checksum type - see [#1018](https://github.com/chocolatey/choco/issues/1018) -- Fix - MSU fails to install with space in path - see [#1177](https://github.com/chocolatey/choco/issues/1177) -- Fix - Unable to disable failOnInvalidOrMissingLicense feature - see [#1069](https://github.com/chocolatey/choco/issues/1069) -- Fix - PowerShell (Start-ChocolateyProcessAsAdmin) should only import the installerModule and not the profile - see [#1013](https://github.com/chocolatey/choco/issues/1013) -- Fix - Automatic Uninstaller should skip when uninstaller executable does not exist - see [#1035](https://github.com/chocolatey/choco/issues/1035) -- Fix - Package installation often fails with ERROR: You cannot call a method on a null-valued expression - see [#1141](https://github.com/chocolatey/choco/issues/1141) -- Fix - Text file determination fails to throw an error because it catches it - see [#1010](https://github.com/chocolatey/choco/issues/1010) -- Fix - Delete the .istext file before the content-type check - see [#1012](https://github.com/chocolatey/choco/issues/1012) -- Fix - new command - don't add unparsed options as the name - see [#1085](https://github.com/chocolatey/choco/issues/1085) -- Fix - Proxy settings ignored for local connections - see [#497](https://github.com/chocolatey/choco/issues/497) -- Fix - RefreshEnv / Update-SessionEnvironment changes current user to SYSTEM - see [#902](https://github.com/chocolatey/choco/issues/902) -- Fix - Set-EnvironmentVariable writes an error when installing Chocolatey as SYSTEM - see [#1043](https://github.com/chocolatey/choco/issues/1043) -- Fix - Get-FtpFile fails with integer overflow when downloading file more than 2gb in size - see [#1098](https://github.com/chocolatey/choco/issues/1098) -- Fix - Uninstall-ChocolateyPackage prints out warning if the passed file path starts and ends with quotes - see [#1039](https://github.com/chocolatey/choco/issues/1039) -- Fix - Get-UninstallRegistryKey fixes/improvements - see [#815](https://github.com/chocolatey/choco/issues/815) -- Fix - Unzip specific folder feature is broken after introducing 7zip - see [#676](https://github.com/chocolatey/choco/issues/676) -- Fix - Join-Path error when installing Chocolatey as SYSTEM - see [#1042](https://github.com/chocolatey/choco/issues/1042) -- Fix - `$env:OS_NAME` is 'Windows' for Windows 10 - see [#1178](https://github.com/chocolatey/choco/issues/1178) -- Fix - choco install relativepath/to/some.nuspec fails - see [#906](https://github.com/chocolatey/choco/issues/906) -- Fix - When pointing to a nupkg, choco should use only that nupkg to install and not a newer version in the same directory - see [#523](https://github.com/chocolatey/choco/issues/523) -- Fix - Automatic uninstaller should split by quotes when necessary - see [#1208](https://github.com/chocolatey/choco/issues/1208) -- [API] Fix - lib should merge the AlphaFS dependency - see [#1148](https://github.com/chocolatey/choco/issues/1148) -- [API] Fix - don't reset loggers on setting custom automatically - see [#1121](https://github.com/chocolatey/choco/issues/1121) -- [API] Fix - Chocolatey file cache adds a 'chocolatey' directory on each install - see [#1210](https://github.com/chocolatey/choco/issues/1210) -- [API] Fix - Getting Local List of Package may leave config in undesirable state - see [#1213](https://github.com/chocolatey/choco/issues/1213) -- Fix - Pro/Business - Chocolatey Licensed Feed May Show Up More Than Once - see [#1166](https://github.com/chocolatey/choco/issues/1166) -- Fix - Pro/Business - Synchronized packages with DLLs are attempted to be imported by Chocolatey's PowerShell Extensions Loader - see [#1041](https://github.com/chocolatey/choco/issues/1041) - -### Improvements - -- [Security] Username and password for `choco apikey` not encrypted in output - see [#1106](https://github.com/chocolatey/choco/issues/1106) -- [Security] Sign Binaries / Authenticode Signatures with Chocolatey Software digital certificate - see [#1214](https://github.com/chocolatey/choco/issues/1214) -- Setting commandExecutionTimeout to 0 means never time out - see [#1202](https://github.com/chocolatey/choco/issues/1202) -- Configure sources to skip proxy - see [#262](https://github.com/chocolatey/choco/issues/262) -- Set proxy information at runtime - see [#1173](https://github.com/chocolatey/choco/issues/1173) -- Start-ChocolateyProcessAsAdmin should not elevate when already elevated - see [#1126](https://github.com/chocolatey/choco/issues/1126) -- Add `--no-progress` cli switch for hidding progress bars - see [#917](https://github.com/chocolatey/choco/issues/917) -- Note web status errors on package install failures - see [#1172](https://github.com/chocolatey/choco/issues/1172) -- Always let Nuget.Core log - see [#1095](https://github.com/chocolatey/choco/issues/1095) -- Make choco get its proxy settings also from environment variables - see [#605](https://github.com/chocolatey/choco/issues/605) -- Remove quotes in process passed to Start-ChocolateyProcessAsAdmin / CommandExecutor - see [#1167](https://github.com/chocolatey/choco/issues/1167) -- Increase download buffer size in Get-FtpFile to speed up downloads - see [#1099](https://github.com/chocolatey/choco/issues/1099) -- Trace network traffic - see [#1182](https://github.com/chocolatey/choco/issues/1182) -- Upgrade 7Zip to 16.04 - see [#1184](https://github.com/chocolatey/choco/issues/1184) -- Do not create .ignore file if outside of Chocolatey location - see [#1180](https://github.com/chocolatey/choco/issues/1180) -- Help should exit zero if called with the help switch, otherwise non-zero on bad commands - see [#473](https://github.com/chocolatey/choco/issues/473) -- "Licensed messages" may address users in a somewhat unprofessional manner - see [#1111](https://github.com/chocolatey/choco/issues/1111) -- Show the entire text to turn on the allowGlobalConfirmation flag - see [#1053](https://github.com/chocolatey/choco/issues/1053) -- Running `choco` should produce name/version and further instructions - see [#1083](https://github.com/chocolatey/choco/issues/1083) -- Typo in Install-ChocolateyPowershellCommand - see [#1088](https://github.com/chocolatey/choco/issues/1088) -- Update `choco new pkg` template to give example of handling nested quoted paths - see [#1067](https://github.com/chocolatey/choco/issues/1067) -- Add Aliases for Install-ChocolateyVsixPackage - see [#1146](https://github.com/chocolatey/choco/issues/1146) -- Add Chocolatey Software to copyright - see [#1209](https://github.com/chocolatey/choco/issues/1209) -- Pro/Business - Feature to Disable Non-Elevated Warnings - see [#1118](https://github.com/chocolatey/choco/issues/1118) -- Pro/Business - Package Throttle - Bitrate limit packages and downloads (support) - see [#454](https://github.com/chocolatey/choco/issues/454) -- Pro/Business - Allow version overrides for local packages - see [#942](https://github.com/chocolatey/choco/issues/942) -- Pro/Business - List include programs should not show items from Package Synchronizer's Programs and Features Package Sync - see [#1205](https://github.com/chocolatey/choco/issues/1205) -- Pro/Business - Show better messaging when unable to load licensed assembly - see [#1145](https://github.com/chocolatey/choco/issues/1145) -- Pro/Business - PowerShell Functions should allow overriding urls - see [#1117](https://github.com/chocolatey/choco/issues/1117) -- Pro/Business - Automatic Uninstaller - allow remove directly - see [#1119](https://github.com/chocolatey/choco/issues/1119) -- Pro/Business - Add Chocolatey Architect edition license SKU - see [#1075](https://github.com/chocolatey/choco/issues/1075) -- Pro/Business - Ensure sync command can be machine parseable - quiet logging - see [#1147](https://github.com/chocolatey/choco/issues/1147) -- Pro/Business - Configure a source to be allowed for self-service - see [#1181](https://github.com/chocolatey/choco/issues/1181) - -## [0.10.3](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.3+is%3Aclosed) (October 7, 2016) - -### Breaking Change - -- Fix - Do Not Check `$LastExitCode` - Only error a package install if script errors or set a different exit code when it is specifically set - see [#1000](https://github.com/chocolatey/choco/issues/1000) - -Starting in v0.9.10, Chocolatey started checking `$LASTEXITCODE` in addition to the script command success as a way to be more helpful in determining package failures. This meant it offered the ability to capture when a script exited with `Exit 1` and handle that accordingly. However that really has never been a recommended scenario for returning errors from scripts and is not seen in the wild anywhere so it is believed that those that may be affected are very few. - -Checking `$LastExitCode` checks the last executable's exit code when the script specifically does not call `Exit`. This can lead to very perplexing failures, such as running a successful xcopy that exits with `2` and seeing package failures without understanding why. Since it is not typically recommended to call `Exit` to return a value from PowerShell because of issues with different hosts, it's less of a concern to only look at explicit failures. For folks that may need it, allow failing a package again by the last external command exit code or `exit` from a PowerShell script. Note that it is not recommended to use exit with a number to return from PowerShell scripts. Instead you should use `$env:ChocolateyExitCode` or `Set-PowerShellExitCode` (first available in v0.9.10) to ensure proper setting of the exit code. - -If you need the prior behavior, please turn on the feature `scriptsCheckLastExitCode`. - -### Bug Fixes - -- Fix - chocolateybeforemodify runs after modifying (moving) chocolatey lib package files - see [#995](https://github.com/chocolatey/choco/issues/995) -- Fix - The refreshenv command throws an error about Write-FunctionCallLogMessage when ran in PowerShell on 0.10.2 - see [#996](https://github.com/chocolatey/choco/issues/996) - -## [0.10.2](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.2+is%3Aclosed) (September 30, 2016) - -We're dubbing this the "Every Joe" release in honor of a friend that just lost his fight with brain cancer. If you want to help further research, please make a donation to a cancer research association of your choosing (e.g. the [American Brain Tumor Assocation](https://give.abta.org/give/261975/#!/donation/checkout)). - -A couple of important fixes/enhancements in this release. Most of the improvements are about providing better feedback to you and fixing minor issues. The big one surrounds when packages set a download path for a file using `$env:TEMP`, choco will ensure that the file can still be found for later use. - -### Bug Fixes - -- Fix - Downloaded file is at old `$env:TEMP\chocolatey\chocolatey` location, but install calls with just `$env:TEMP\chocolatey\` location - see [#969](https://github.com/chocolatey/choco/issues/969) -- Fix - [Pro/Business] UseOriginalLocation fails when there is no 64bit file - see [#972](https://github.com/chocolatey/choco/issues/972) -- Fix - Do not use unparsed options as package names - see [#983](https://github.com/chocolatey/choco/issues/983) - -### Improvements - -- Start-ChocolateyProcessAsAdmin enhancements - see [#977](https://github.com/chocolatey/choco/issues/977) -- Log PowerShell function calls better - see [#976](https://github.com/chocolatey/choco/issues/976) -- Allow environment variables in some config settings - see [#971](https://github.com/chocolatey/choco/issues/971) -- [Pro/Business] Provide license type to environment variables - see [#968](https://github.com/chocolatey/choco/issues/968) -- Note that chocolateyUninstall.ps1 may no longer required in template - see [#982](https://github.com/chocolatey/choco/issues/982) -- Provide guidance when licensed only options are passed to FOSS - see [#984](https://github.com/chocolatey/choco/issues/984) -- Rollback automatically when a user cancels an operation - see [#985](https://github.com/chocolatey/choco/issues/985) -- Explain how to workaround a failing uninstall - see [#573](https://github.com/chocolatey/choco/issues/573) -- Remove extra forward slashes in url - see [#986](https://github.com/chocolatey/choco/issues/986) -- Side by side uninstall enhancements - see [#992](https://github.com/chocolatey/choco/issues/992) - -## [0.10.1](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.1+is%3Aclosed) (September 19, 2016) - -We're dubbing this the "Shhh! Keep that secret please" release. We've found that when passing in passwords and other sensitive arguments, those items can end up in the logs in clear text. We've addressed this in [#948](https://github.com/chocolatey/choco/issues/948) and [#953](https://github.com/chocolatey/choco/issues/953). When it comes to passing sensitive arguments through to native installers, you can set up environment variables with those sensitive args and pass those arguments directly through to `Start-ChocolateyProcessAsAdmin`. If you prefer a better experience, the licensed version allows passing sensitive options directly through choco.exe as `--install-arguments-sensitive` and `--package-parameters-sensitive`. Read more in the [Licensed CHANGELOG](https://github.com/chocolatey/choco/blob/master/CHANGELOG_LICENSED.md). - -Perhaps the biggest improvement in this release is that Chocolatey will automatically look to see if it can download binaries over HTTPS when provided an HTTP url. If so, Chocolatey will switch to downloading the binaries over SSL. This provides better security in downloading and knowing you are getting the binary from the source location instead of a possible man in the middle location, especially when the package does not provide checksums for verification. - -Another improvement you may not even notice, but we think you will love is that Chocolatey now supports TLS v1.2 transport which presents a nice transparent increase in security. You will need to have at least .NET Framework 4.5 installed to take advantage of this feature. - -### Features - -- [Security] Support TLS v1.2 - see [#458](https://github.com/chocolatey/choco/issues/458) -- [Security] Attempt to download packages via HTTPS connection - see [#746](https://github.com/chocolatey/choco/issues/746) -- [Security] Pro/Business - Pass sensitive arguments to installers - see [#948](https://github.com/chocolatey/choco/issues/948) -- Search (and info) by version - see [#935](https://github.com/chocolatey/choco/issues/935) - -### Bug Fixes - -- [Security] Fix - Passwords in command line options are logged in clear text - see [#953](https://github.com/chocolatey/choco/issues/953) -- [Security] Fix - For PowerShell v2 - if switch down to SSLv3 protocol fails, go back to original protocol - see [#958](https://github.com/chocolatey/choco/issues/958) -- Fix - Unzipping to ProgramFiles/System32 is Subject to File System Redirection - see [#960](https://github.com/chocolatey/choco/issues/960) -- Fix - Run without login - see [#945](https://github.com/chocolatey/choco/issues/945) -- Fix - Support Long Paths - see [#934](https://github.com/chocolatey/choco/issues/934) -- Fix - help should not issue warning about elevated command shell - see [#893](https://github.com/chocolatey/choco/issues/893) -- Fix - Licensed Feed cannot be disabled - see [#959](https://github.com/chocolatey/choco/issues/959) -- Fix - Choco with unknown command should show help menu - see [#938](https://github.com/chocolatey/choco/issues/938) -- Fix - Get-FtpFile error when file is missing (called through Get-ChocolateyWebFile) - see [#920](https://github.com/chocolatey/choco/issues/920) -- Fix - Skip Get-WebFileName for FTP - see [#957](https://github.com/chocolatey/choco/issues/957) -- Fix - Chocolatey-InstallChocolateyPackage fix for double chocolatey folder name is not also applied to the passed in file name - see [#908](https://github.com/chocolatey/choco/issues/908) -- Fix - Start-ProcessAsAdmin - working directory should be from the location of the executable - see [#937](https://github.com/chocolatey/choco/issues/937) -- [POSH Host] Fix - PowerShell Host - Package scripts setting values can affect packages that depend on them - see [#719](https://github.com/chocolatey/choco/issues/719) -- Fix - Transactional install - pending check may fail if the lib folder doesn't exist - see [#954](https://github.com/chocolatey/choco/issues/954) -- Fix - Start-ChocolateyProcessAsAdmin Module Import for PowerShell causes errors - see [#901](https://github.com/chocolatey/choco/issues/901) - -### Improvements - -- Transactional Install - Improve concurrent operations (pending) - see [#943](https://github.com/chocolatey/choco/issues/943) -- Uninstall-ChocolateyPackage should set unrecognized fileType to exe - see [#964](https://github.com/chocolatey/choco/issues/964) -- Powershell functions - Allow access to package title, not only ID - see [#925](https://github.com/chocolatey/choco/issues/925) -- Option to apply package parameters / install arguments to dependent packages - see [#839](https://github.com/chocolatey/choco/issues/839) -- Get-ChocolateyWebFile download check enhancements - see [#952](https://github.com/chocolatey/choco/issues/952) -- Do not treat unknown checksum types as MD5 - see [#932](https://github.com/chocolatey/choco/issues/932) -- Pro/Business - Install-ChocolateyPackage - UseOriginalLocation - see [#950](https://github.com/chocolatey/choco/issues/950) -- Auto determine checksum type - see [#922](https://github.com/chocolatey/choco/issues/922) -- Ensure PowerShell functions have parameter name parity - see [#941](https://github.com/chocolatey/choco/issues/941) -- Output from installer should go to verbose log - see [#940](https://github.com/chocolatey/choco/issues/940) - -## [0.10.0](https://github.com/chocolatey/choco/issues?q=milestone%3A0.10.0+is%3Aclosed) (August 11, 2016) - -What was planned for 0.9.10.4 is now 0.10.0. This is due partly to a breaking change we are making for security purposes and a move to provide better a better versioning scheme for the remainder of the sub-v1 versions of Chocolatey. Instead of 0.y.z.0 being considered where major verions occur in the sub 1 series, 0.y.0 will now be considered where those major versions occur. We also are moving right along towards v1 (and hope to be there in 2017). - -0.10.0 carries the fixes for 0.9.10.4 and includes a major security enhancement (checksum requirement). - -### Breaking Change - -- [Security] Checksum requirement and enhancements - see [#112](https://github.com/chocolatey/choco/issues/112) - -Checksums in package scripts are meant as a measure to validate the originally intended downloaded resources used in the creation of a package are the same files that are received at a future date. This also ensures that the same files that are checked by all parts of moderation (if applicable) are the same files that are received by users for a package. This is seen mostly on the community repository because it is public and packages are subject to copyright laws (distribution rights), which typically requires the package scripts to download software from the official distribution locations. The Chocolatey framework has had the ability to use checksums in package scripts since [July 2014](https://docs.chocolatey.org/en-us/choco/release-notes#july-3-2014). - -**What is the requirement?** choco will now fail if a package download resources from HTTP/FTP and does not use checksums to verify those downloaded resources. The requirement for HTTP/FTP is [#112](https://github.com/chocolatey/choco/issues/112). We are considering also requiring it for [HTTPS (#895)](https://github.com/chocolatey/choco/issues/895) as well. You can optionally set a feature (`allowEmptyChecksumsSecure`) to ensure packages using HTTPS also use checksums. - -**How does this protect the community anymore than before?** During moderation review, there is a check of these downloaded binaries against VirusTotal (which verifies these binaries against 50-60+ different virus scanners). The binaries are also verified for installation purposes against a test computer. With an independent 3rd party checksum in the package itself, it guarantees that the files received by a user from those remote sources are the exact same files that were used in the verification process. - -**Why the requirement, and why now?** This is a measure of protection for the Chocolatey community. HTTP is easy to hack with both DNS poisoning and MITM (man in the middle) attacks. Without independent verification of the integrity of the downloaded resources, users can be left susceptible to these issues. We've been planning a move to require checksums for awhile now, with a planned longer and smoother transition for package maintainers to get packages updated to reduce breakages. Unfortunately there was a recent event with [FOSSHub getting hacked](https://www.zdnet.com/article/fosshub-serves-up-mbr-compromising-versions-of-audacity-and-classic-shell/) (the [community repository had 8 possibly affected packages](https://us8.campaign-archive.com/?u=86a6d80146a0da7f2223712e4&id=f2fe8dbe6b) and [we quickly took action](https://us8.campaign-archive.com/?u=86a6d80146a0da7f2223712e4&id=2cbe87d486)), which necessitated a need for us to move in a much swifter fashion to ensure the protection of the community sooner, rather than later. The changes in Chocolatey represented by the checksum changes are a major step in the process to ensure protection. Requiring for HTTPS as well will mitigate any future compromises of software distribution sites that are used with Chocolatey packages. - -**Can I shut this behavior off or opt out per package?** -You can shut off the checksum requirement by enabling the feature `allowEmptyChecksums`. This will return Chocolatey to previous behavior. We strongly recommend against it. - -You can shut it off or turn it per package install/upgrade with `--allow-empty-checksums` and `--require-checksums`, respectively. See https://docs.chocolatey.org/en-us/choco/commands/install / https://docs.chocolatey.org/en-us/choco/commands/upgrade. - -You can also disable the feature `allowEmptyChecksumsSecure` to enforce checksums for packages that download from secure locations (HTTPS). - -**Other things I should know?** Users also now have the ability to pass their own checksums and checksumtypes into the install. See https://docs.chocolatey.org/en-us/choco/commands/install / https://docs.chocolatey.org/en-us/choco/commands/upgrade. - -### Known Issue - -- [Known Issues](https://github.com/chocolatey/choco/labels/Bug) - -### Feature - -- Pro/Business - Download a package without installing it - see [#108](https://github.com/chocolatey/choco/issues/108) - -### Bug Fixes - -- Fix - Installing choco on Windows 10 Vagrant box stops Vagrant from being able to manage the box - see [#834](https://github.com/chocolatey/choco/issues/834) -- Fix - 64bit 7z.exe on 32bit system in chocolatey\tools - see [#836](https://github.com/chocolatey/choco/issues/836) -- Fix - [POSH Host] PowerShell exit code does not reset between packages in a single run - see [#854](https://github.com/chocolatey/choco/issues/854) -- Fix - Uninstall-ChocolateyZipPackage is failing - see [#871](https://github.com/chocolatey/choco/issues/871) -- Fix - "C:\Program Files\WindowsPowerShell\Modules" is missing in PSModulePath for cmd.exe [#830](https://github.com/chocolatey/choco/issues/830) -- Fix - Environment variables update fixes [#840](https://github.com/chocolatey/choco/issues/840) -- Fix - Handle null items better - see [#853](https://github.com/chocolatey/choco/issues/853) -- Fix - HKCU may not have Environment (Install of Chocolatey) - see [#375](https://github.com/chocolatey/choco/issues/375) -- Fix - Progress of download does not clear the whole output line - see [#875](https://github.com/chocolatey/choco/issues/875) -- Fix - Wrong download progress reported during package upgrade - see [#872](https://github.com/chocolatey/choco/issues/872) -- Fix - Uninstall not supporting side-by-side => ChocolateyUninstall.ps1 not run - see [#862](https://github.com/chocolatey/choco/issues/862) -- Fix - Uninstall ignores the version parameter - see [#861](https://github.com/chocolatey/choco/issues/861) -- Fix - Search by exact or by id only is case sensitive for remote sources - see [#889](https://github.com/chocolatey/choco/issues/889) -- Fix - Deprecated links inserted in .nuspec files created by `choco new ...` - see [#870](https://github.com/chocolatey/choco/issues/870) -- Fix - Get-OSArchitectureWidth doesn't do what it says it does - see [#828](https://github.com/chocolatey/choco/issues/828) -- Fix - When Choco fails to get a package from NuGet Core, fail the package with exit code 1 - see [#867](https://github.com/chocolatey/choco/issues/867) -- Fix - Illegal characters in path - see [#857](https://github.com/chocolatey/choco/issues/857) -- Fix - Get-OSArchitectureWidth doesn't do what it says it does - see [#828](https://github.com/chocolatey/choco/issues/828) -- Fix - Pro/Business - Choco install config file fails on licensed assembly - see [#866](https://github.com/chocolatey/choco/issues/866) -- Fix - DISM /all doesn't run anywhere but Windows 6.2 -- no dependencies get installed - see [#897](https://github.com/chocolatey/choco/issues/897) - -### Improvements - -- Do not install tab completion (edit of profile) under certain conditions - see [#833](https://github.com/chocolatey/choco/issues/833) -- Choco install with packages.config should print out the packages to install - see [#878](https://github.com/chocolatey/choco/issues/878) -- Larger default log file size and retention - see [#852](https://github.com/chocolatey/choco/issues/852) -- Allow getting installer type to be overridden - see [#885](https://github.com/chocolatey/choco/issues/885) -- Pack - Add optional output folder option - see [#598](https://github.com/chocolatey/choco/issues/598) -- Little command name correction on init.ps1 - see [#595](https://github.com/chocolatey/choco/issues/595) -- Tab completion - don't query if there is a file in the folder that meets completion - see [#847](https://github.com/chocolatey/choco/issues/847) - -## [0.9.10.3](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.10.3+is%3Aclosed) (June 23, 2016) - -### Bug Fixes - -- Fix - Ignore ValidPackage Exit Codes for Real - see [#827](https://github.com/chocolatey/choco/issues/827) -- Fix - Cache folder running under SYSTEM account should be C:\Windows\TEMP - see [#826](https://github.com/chocolatey/choco/issues/826) -- Fix - Built-in 7zip doesn't behave properly - see [#775](https://github.com/chocolatey/choco/issues/775) -- Fix - Successful installer exit codes not recognized by choco should return 0 - see [#821](https://github.com/chocolatey/choco/issues/821) -- Fix - NotSilent fails with "Cannot bind argument to parameter statements because it is an empty string" - see [#819](https://github.com/chocolatey/choco/issues/819) -- Fix - Silent Args being passed as a string array cause package failure - see [#808](https://github.com/chocolatey/choco/issues/808) - -### Improvements - -- Hold pending check for 10 seconds / provide means of explicitly overriding the transactional install cleanup - see [#822](https://github.com/chocolatey/choco/issues/822) -- Pro/Business - Add runtime skip option to allow skipping the virus scanner - see [#786](https://github.com/chocolatey/choco/issues/786) - -## [0.9.10.2](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.10.2+is%3Aclosed) (June 19, 2016) - -### Bug Fixes - -- Fix - Chocolatey Licensed is unable to find 0.9.10.x (only 0.9.10.0) - see [#814](https://github.com/chocolatey/choco/issues/814) -- Fix - Logging is broken in some packages due to new TEMP directory - see [#813](https://github.com/chocolatey/choco/issues/813) -- [API] Fix - When performing an Install/Uninstall/Upgrade operation through the API, an error is throw for "chocolatey.resources" - see [#811](https://github.com/chocolatey/choco/issues/811) - -### Improvement - -- Ensure log file path exists - and fix the log file arguments if necessary - see [#758](https://github.com/chocolatey/choco/issues/758) - -## [0.9.10.1](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.10.1+is%3Aclosed) (June 18, 2016) - -### Bug Fix - -- Fix - Cannot bind argument to parameter 'exitCode' because it is null - see [#810](https://github.com/chocolatey/choco/issues/810) - -### Improvement - -- [Security] Upgrade to 7zip 16.02 to overcome CVE-2016-2334/CVE-2016-2335 - see [#812](https://github.com/chocolatey/choco/issues/812) - -## [0.9.10](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.10+is%3Aclosed) (June 17, 2016) - -The "I got 99 problems, but a package manager ain't one" release. With the release of 0.9.10 (or if you prefer 0.9.10.0), we're about to make everything 100% better in your Windows package management world. We've addressed over 100 features and bugs in this release. We looked at how we could improve PowerShell and we've come out with a [competely internal host](https://github.com/chocolatey/choco/issues/8) that can Prompt and Read-Host in a way that times out and selects default values after a period of time. Speaking of PowerShell, how about some tab completion `choco ` to `choco install node`? How about never having to [close and reopen your shell again](https://github.com/chocolatey/choco/issues/664)? - -Alternative sources (`-source webpi`, `--source windowsfeature`, etc) are back! I mean, am I right?! Have you heard of auto uninstaller? If Chocolatey has installed something that works with Programs and Features, Chocolatey knows how to uninstall it without an uninstall script about 90+% of the time. This feature was in beta for the 0.9.9 series, it is on by default in 0.9.10 (unless you disabled it after trying it, you will need to reenable it, see `choco feature` for more details). - -Here's one you probably never knew existed - extensions. Chocolatey has had the ability to extend itself by adding PowerShell modules for years, and most folks either didn't know it existed or have never used them. We've enhanced them a bit in preparation for the licensed version of Chocolatey. - -We redesigned our `choco new` default packaging template and we've made managing templates as easy as managing packages. - -`choco search`/`choco list` has so many enhancements, you may not need to visit dot org again. [See it in action](xref:choco-command-list#see-it-in-action). -- [search -v provides moderation related information and a world of nuspec information](https://github.com/chocolatey/choco/issues/493) -- [search by id only](https://github.com/chocolatey/choco/issues/663) -- [search by id exact](https://github.com/chocolatey/choco/issues/453) -- [search by approved only, not broken, and/or by download cache](https://github.com/chocolatey/choco/issues/670) -- [sort by version](https://github.com/chocolatey/choco/issues/668) -- [search with paging](https://github.com/chocolatey/choco/issues/427) - -There are 150 tickets closed for this release! We've included remediation steps for when a breaking change affects you. Mostly if you have been using Chocolatey in a recommended way, you won't even notice any adverse changes. There are a number of things we thought to highlight, and quite a few security enhancements coming in this release (look for the [Security] tag on the ticket summary). - -### Breaking Changes - -- Only fail automation scripts (chocolateyInstall.ps1) if the script returns non-zero exit code - see [#445](https://github.com/chocolatey/choco/issues/445) - -The 0.9.8 series would only fail a package with terminating errors. The 0.9.9 series took that a bit further and started failing packages if anything wrote to stderr. It turns out that is a bad idea. Only when PowerShell exits with non-zero (which comes with terminating errors) should the package fail due to this. If you need the old behavior of the 0.9.9 series, you can get it back with a switch (`--fail-on-standard-error` and its aliases) and/or a feature flip (`failOnStandardError`). - -- Fix - Force reinstall, force upgrade, and uninstall should delete the download cache - see [#590](https://github.com/chocolatey/choco/issues/590) - -If you set a custom cache directory for downloads, it will no longer use a "chocolatey" subdirectory under that. You may need to make any adjustments if this is going to affect you. - -- Exit with the same exit code as the software being installed - see [#512](https://github.com/chocolatey/choco/issues/512) - -There are more exit codes from Chocolatey now that indicate success -`0`, `1605`, `1614`, `1641`, and `3010`. You may need to adjust anything you were using that would only check for 0 and nonzero. -If you need the previous behavior, be sure to disable the feature `usePackageExitCodes` or use the `--ignore-package-exit-codes` switch in your choco commands. - -- PowerShell module functions adjusted for automatic documentation - see [#697](https://github.com/chocolatey/choco/issues/697) - -If you were using any of the functions in a non-recommended way or not compliant with the examples, you are going to find breakages in the functions as some of the things that were called out as non-optional are now enforced. This shouldn't affect most folks. - -- [Security] Explicit permissions - remove inheritance/lock down to admins - see [#398](https://github.com/chocolatey/choco/issues/398) - -This further restricts the default installation location by removing all permissions and inheritance of permissions, explicitly giving Administrator/LocalSystem to Full access, and Users are granted Read and Execute. - -### Known Issue - -- [Known Issues](https://github.com/chocolatey/choco/labels/Bug) - -### Features - -- Alternative Sources - see [#14](https://github.com/chocolatey/choco/issues/14) -- [POSH Host] Use Internal PowerShell Host - see [#8](https://github.com/chocolatey/choco/issues/8) -- Run a script before uninstall/upgrade (chocolateyBeforeModify.ps1) to allow for things like services to shutdown - see [#268](https://github.com/chocolatey/choco/issues/268) -- Manage package templates with a specially named package and special package folder - see [#542](https://github.com/chocolatey/choco/issues/542) -- Support for custom headers - see [#332](https://github.com/chocolatey/choco/issues/332) -- [Security] Show moderation-related information in search results - see [#493](https://github.com/chocolatey/choco/issues/493) -- New Helper - Get-ToolsLocation helper (replacement for Get-BinRoot) - see [#631](https://github.com/chocolatey/choco/issues/631) -- Choco list/search should have exact filter search - see [#453](https://github.com/chocolatey/choco/issues/453) -- RefreshEnv (Refresh Environment Variables) Should also work in PowerShell - see [#664](https://github.com/chocolatey/choco/issues/664) -- Provide PowerShell tab completion for Chocolatey - see [#412](https://github.com/chocolatey/choco/issues/412) -- [Security] Sign the PowerShell scripts and assemblies - see [#501](https://github.com/chocolatey/choco/issues/501) -- Add a `choco info` command to show info for one package - see [#644](https://github.com/chocolatey/choco/issues/644) -- Mark packages pending until install completes successfully - see [#198](https://github.com/chocolatey/choco/issues/198) -- Resolve sources by name - see [#356](https://github.com/chocolatey/choco/issues/356) -- Uninstall-ChocolateyEnvironmentVariable function - see [#772](https://github.com/chocolatey/choco/issues/772) -- Pro/Business - Ubiquitous Install Directory Switch - see [#258](https://github.com/chocolatey/choco/issues/258) -- Pro/Business - Runtime Virus Scanning - see [virus scanning](https://docs.chocolatey.org/en-us/features/virus-check) -- Pro/Business - Private CDN cache for downloads - see [private CDN cache](https://docs.chocolatey.org/en-us/features/private-cdn) -- Pro/Business - Sync "choco installed status" with "Windows installed status" - see [#567](https://github.com/chocolatey/choco/issues/567) - -### Bug Fixes - -- [Security] Fix - Only load the Chocolatey PowerShell module from a known location - see [#560](https://github.com/chocolatey/choco/issues/560) -- [Security] Fix - Package source authentication at http://location/path doesn't also use http://location/ (base url) - see [#466](https://github.com/chocolatey/choco/issues/466) -- [Security] Fix - When defining a proxy without credentials - proxy password is shown in plain text - see [#503](https://github.com/chocolatey/choco/issues/503) -- [Security] Fix - Fully qualify shutdown command - see [#702](https://github.com/chocolatey/choco/issues/702) -- [Security] Fix - MSI packages fail install with `Could not find 'msiexec'` - see [#723](https://github.com/chocolatey/choco/issues/723) -- Fix - Force should set allow-downgrade to true - see [#585](https://github.com/chocolatey/choco/issues/585) -- Fix - Do not use NuGet package cache - see [#479](https://github.com/chocolatey/choco/issues/479) -- Fix - Pack doesn't include chocolatey-specific metadata - see [#607](https://github.com/chocolatey/choco/issues/607) -- Fix - TEMP environment variable is 8.3 Path on some systems - see [#532](https://github.com/chocolatey/choco/issues/532) -- Fix - `$packageName` should be present for zip uninstalls in uninstall script template - see [#534](https://github.com/chocolatey/choco/issues/534) -- Fix - Debug/Verbose messages not logged in automation scripts (chocolateyInstall.ps1) - see [#520](https://github.com/chocolatey/choco/issues/520) -- Fix - Escape log output for variables that have data from external sources - see [#565](https://github.com/chocolatey/choco/issues/565) -- Fix - Choco new silentargs can't pass in args in the param=value format - see [#510](https://github.com/chocolatey/choco/issues/510) -- Fix - Exception if no source is enabled - see [#490](https://github.com/chocolatey/choco/issues/490) -- Fix - Chocolatey command help output written to standard error instead of standard out - see [#468](https://github.com/chocolatey/choco/issues/468) -- Fix - Logger doesn't clear cached NullLoggers - see [#516](https://github.com/chocolatey/choco/issues/516) -- Fix - DISM "/All" argument in the wrong position - see [#480](https://github.com/chocolatey/choco/issues/480) -- Fix - Pro - Installing/uninstalling extensions should rename files in use - see [#594](https://github.com/chocolatey/choco/issues/594) -- Fix - Running Get-WebFileName in PowerShell 5 fails and sometimes causes package errors - see [#603](https://github.com/chocolatey/choco/issues/603) -- Fix - Merging assemblies on a machine running .Net 4.5 or higher produces binaries incompatible with .Net 4 - see [#392](https://github.com/chocolatey/choco/issues/392) -- Fix - API - Incorrect log4net version in chocolatey.lib dependencies - see [#390](https://github.com/chocolatey/choco/issues/390) -- [POSH Host] Fix - Message after Download progress is on the same line sometimes - see [#525](https://github.com/chocolatey/choco/issues/525) -- [POSH Host] Fix - PowerShell internal process - "The handle is invalid." - see [#526](https://github.com/chocolatey/choco/issues/526) -- [POSH Host] Fix - The handle is invalid - when output is being redirected and a package attempts to write to a filestream - see [#572](https://github.com/chocolatey/choco/issues/572) -- [POSH Host] Fix - Write-Host adding multiple line breaks - see [#672](https://github.com/chocolatey/choco/issues/672) -- [POSH Host] Fix - PowerShell Host doesn't show colorization overrides - see [#674](https://github.com/chocolatey/choco/issues/674) -- [POSH Host] Fix - $profile is empty string when installing packages - does not automatically install the ChocolateyProfile - see [#667](https://github.com/chocolatey/choco/issues/667) -- [POSH Host] Fix - Getting LCID doesn't work properly with the built-in PowerShell - see [#741](https://github.com/chocolatey/choco/issues/741) -- [POSH Host] Fix - Host.Version should return actual PowerShell version - see [#708](https://github.com/chocolatey/choco/issues/708) -- Fix - Verbose shows in output on debug switch - see [#611](https://github.com/chocolatey/choco/issues/611) -- Fix - Get-ChocolateyUnzip captures files that don't belong to the package / Unzip should not do a full disk scan - see [#616](https://github.com/chocolatey/choco/issues/616) and [#155](https://github.com/chocolatey/choco/issues/155) -- Fix - Package succeeds but software install silently fails when Install-ChocolateyInstallPackage has the wrong arguments - see [#629](https://github.com/chocolatey/choco/issues/629) -- Fix - ShimGen handling of spaces and arguments that have shimgen in them - see [#647](https://github.com/chocolatey/choco/issues/647) -- Fix - PowerShell v2 - Choco installer messages can't actually be warnings (causes FileStream errors) - see [#666](https://github.com/chocolatey/choco/issues/666) -- Fix - Installing chocolatey removes $env:PSModulePath changes for current PowerShell session - see [#295](https://github.com/chocolatey/choco/issues/295) -- Fix - Notice for Get-BinRoot deprecation won't be displayed - see [#673](https://github.com/chocolatey/choco/issues/673) -- Fix - choco new creates a bad ChocolateyUninstall.ps1 script which does not work. - see [#460](https://github.com/chocolatey/choco/issues/460) -- Fix - ShimGen fails when file metadata has strings that need literals - see [#677](https://github.com/chocolatey/choco/issues/677) -- Fix - Install-ChocolateyPath Expands Variables in PATH, Overwriting Preexisting Variables - see [#303](https://github.com/chocolatey/choco/issues/303) -- Fix - Install-ChocolateyShortcut gives invalid warning when target is a web url - see [#592](https://github.com/chocolatey/choco/issues/592) -- Fix - Argument Parsing failures should be reported as warnings and not debug messages - see [#571](https://github.com/chocolatey/choco/issues/571) -- Fix - choco pack returns zero exit code when Nuget.Core validation errors - see [#469](https://github.com/chocolatey/choco/issues/469) -- Fix - `Install-ChocolateyPath` updates `PATH` to `REG_SZ`, which may break using Windows dir and system32 tools - see [#699](https://github.com/chocolatey/choco/issues/699) -- Fix - Removing environment variables sets empty environment variables - see [#724](https://github.com/chocolatey/choco/issues/724) -- Fix - Environment Variable Changes Require Reboot - see [#728](https://github.com/chocolatey/choco/issues/728) -- Fix - Get-WebFileName determines strange file name - see [#727](https://github.com/chocolatey/choco/issues/727) -- Fix - Package params are also applied to dependent package - see [#733](https://github.com/chocolatey/choco/issues/733) -- Fix - Use package name/version from environment, not parameters - see [#751](https://github.com/chocolatey/choco/issues/751) -- Fix - Get-WebFileName Does Not Match on Invalid Characters - see [#753](https://github.com/chocolatey/choco/issues/753) -- Fix - `choco new` cannot introduce multistage folder hierarchy template - see [#706](https://github.com/chocolatey/choco/issues/706) -- Fix - Empty $env:ChocolateyToolsLocation combine error - see [#756](https://github.com/chocolatey/choco/issues/756) -- Fix - Installing chocolatey removes $env:PSModulePath changes for current powershell session - see [#295](https://github.com/chocolatey/choco/issues/295) -- Fix - Some environment variables are set too early for options/switches to have an effect - see [#620](https://github.com/chocolatey/choco/issues/620) -- [API] Fix - Issue when attempting to execute run command through API - see [#769](https://github.com/chocolatey/choco/issues/769) -- Fix - Logging of upgrade messages - placement of some messages is incorrect - see [#557](https://github.com/chocolatey/choco/issues/557) -- Fix - Get-WebFile fails with - The term '//continue' is not recognized as the name of a cmdlet - see [#789](https://github.com/chocolatey/choco/issues/789) -- Fix - Unable to read registry snapshot file - see [#487](https://github.com/chocolatey/choco/issues/487) -- Fix - Pro/Business - Licensed version has an incorrect dependency on PowerShell assemblies and will only load v3 and above - see [#799](https://github.com/chocolatey/choco/issues/799) -- Fix - Exit codes in package scripts should work - see [#802](https://github.com/chocolatey/choco/issues/802) -- Fix - Running choco new creates a bad nuspec - see [#801](https://github.com/chocolatey/choco/issues/801) - -### Improvements - -- AutoUninstaller is on by default - see [#308](https://github.com/chocolatey/choco/issues/308) -- Use the actual download file name instead of providing one - see [#435](https://github.com/chocolatey/choco/issues/435) -- Unset Configuration Values - see [#551](https://github.com/chocolatey/choco/issues/551) -- Ability to run "choco upgrade all" ignoring specific packages - see [#293](https://github.com/chocolatey/choco/issues/293) -- Extensions enhancements - see [#588](https://github.com/chocolatey/choco/issues/588) -- Show human-readable file sizes when downloading - see [#363](https://github.com/chocolatey/choco/issues/363) -- [Security] Warn about environment changes - see [#563](https://github.com/chocolatey/choco/issues/563) -- Warn when execution timeout has elapsed - see [#561](https://github.com/chocolatey/choco/issues/561) -- Update nuspec to make it easier to get started - see [#535](https://github.com/chocolatey/choco/issues/535) -- Suppress verbose output to verbose - like with 7-zip - see [#476](https://github.com/chocolatey/choco/issues/476) -- Choco push moderation message only on push to dot org - see [#601](https://github.com/chocolatey/choco/issues/601) -- Allow tools/bin root to be root of the drive again - see [#628](https://github.com/chocolatey/choco/issues/628) -- File description of ShimGen shims should match original as closely as possible - see [#374](https://github.com/chocolatey/choco/issues/374) -- Shim Generation should automatically detect GUI - see [#634](https://github.com/chocolatey/choco/issues/634) -- Don't show 32 bit wording unless there is explicitly both versions available - see [#642](https://github.com/chocolatey/choco/issues/642) -- Allow passing arbitrary key/value arguments to new command when generating packages from templates - see [#658](https://github.com/chocolatey/choco/issues/658) -- Choco search/list should be able to search just by Id - see [#663](https://github.com/chocolatey/choco/issues/663) -- Search by approved, by not broken, by download cache - see [#670](https://github.com/chocolatey/choco/issues/670) -- Save nuspec files with package installs - see [#623](https://github.com/chocolatey/choco/issues/623) -- Show a prompt character when asking a multiple choice question - see [#184](https://github.com/chocolatey/choco/issues/184) -- When prompting for a user yes/no answer, use a short [y/n] representation - see [#181](https://github.com/chocolatey/choco/issues/181) -- Default package template should include LICENSE.txt and VERIFICATION.txt for packages with binaries - see [#675](https://github.com/chocolatey/choco/issues/675) -- choco list/search aliases for -v - '-detail' and '-detailed' - see [#646](https://github.com/chocolatey/choco/issues/646) -- Log normal output to a secondary log - see [#682](https://github.com/chocolatey/choco/issues/682) -- Display Package test status information on install/upgrade - see [#696](https://github.com/chocolatey/choco/issues/696) -- Report when reboots are necessary from package installs - see [#712](https://github.com/chocolatey/choco/issues/712) -- Report loaded extensions - see [#715](https://github.com/chocolatey/choco/issues/715) -- Exit with specific codes on certain actions - see [#707](https://github.com/chocolatey/choco/issues/707) -- Determine if Downloaded File is HTML or Plain Text - see [#649](https://github.com/chocolatey/choco/issues/649) -- Interactively prompt with timeout on some questions - see [#710](https://github.com/chocolatey/choco/issues/710) -- [POSH Host] Exit code from PowerShell Host should be useful - see [#709](https://github.com/chocolatey/choco/issues/709) -- Update environment for scripts after setting environment variables - see [#729](https://github.com/chocolatey/choco/issues/729) -- Clean up any temp nuget folder actions after NuGet operations - see [#622](https://github.com/chocolatey/choco/issues/622) -- Ensure Web Requests and Responses Do Not Timeout - make configurable - see [#732](https://github.com/chocolatey/choco/issues/732) -- Combine timeout from push and execution timeout as one parameter - see [#752](https://github.com/chocolatey/choco/issues/752) -- Override autouninstaller / failonautouninstaller fail with switches for uninstall - see [#515](https://github.com/chocolatey/choco/issues/515) -- Offer to remove actual package (*.install/*.portable) when removing meta/virtual package - see [#735](https://github.com/chocolatey/choco/issues/735) -- Provide more info in package summary - see [#455](https://github.com/chocolatey/choco/issues/455) -- Report install location - see [#689](https://github.com/chocolatey/choco/issues/689) -- Track MSI Information Better - see [#755](https://github.com/chocolatey/choco/issues/755) -- Support for client certificates - see [#399](https://github.com/chocolatey/choco/issues/399) -- choco feature list formatting enhancements - see [#742](https://github.com/chocolatey/choco/issues/742) -- choco new --original-template - see [#737](https://github.com/chocolatey/choco/issues/737) -- Update Get-FtpFile with fixes for Get-WebFile - see [#765](https://github.com/chocolatey/choco/issues/765) -- Rename Get-ProcessorBits as a more appropriately named Get-OSArchitectureWidth - see [#713](https://github.com/chocolatey/choco/issues/713) -- Allow passing no 32-bit url and fail the package on 32-bit systems - see [#527](https://github.com/chocolatey/choco/issues/527) -- Enhance Install-ChocolateyShortcut to support WindowStyle, Pin to Taskbar and Run As Administrator checkbox - see [#519](https://github.com/chocolatey/choco/issues/519) -- [Security] Allow hashing files for checksums with FIPS compliant algorithms - see [#446](https://github.com/chocolatey/choco/issues/446) -- After upgrading provide summary of upgraded packages - see [#759](https://github.com/chocolatey/choco/issues/759) -- Web functions - Check for local file and return early - see [#781](https://github.com/chocolatey/choco/issues/781) -- Refresh environment variables after each install - see [#439](https://github.com/chocolatey/choco/issues/439) -- Capture Arguments for a Package during Install/Upgrade - see [#358](https://github.com/chocolatey/choco/issues/358) -- If config update fails, log to debug instead of warn - see [#793](https://github.com/chocolatey/choco/issues/793) -- Remove extra empty lines when doing choco upgrade all - see [#796](https://github.com/chocolatey/choco/issues/796) -- Mention required permissions if user has no access - see [#794](https://github.com/chocolatey/choco/issues/794) -- Pro/Business - Also check for license in User Profile location - see [#606](https://github.com/chocolatey/choco/issues/606) -- Pro/Business - Set download cache information if available - see [#562](https://github.com/chocolatey/choco/issues/562) -- Pro/Business - Allow commands to be added - see [#583](https://github.com/chocolatey/choco/issues/583) -- Pro/Business - Load/Provide hooks for licensed version - see [#584](https://github.com/chocolatey/choco/issues/584) -- Pro/Business - On valid license, add pro/business source automatically - see [#604](https://github.com/chocolatey/choco/issues/604) -- Pro/Business - Add switch to fail on invalid or missing license - see [#596](https://github.com/chocolatey/choco/issues/596) -- Pro/Business - add ignore invalid switches/parameters - see [#586](https://github.com/chocolatey/choco/issues/586) -- Pro/Business - Don't prompt to upload file for virus scanning if it is too large - see [#695](https://github.com/chocolatey/choco/issues/695) -- Pro/Business - add 'support' command - see [#745](https://github.com/chocolatey/choco/issues/745) -- Pro/Business - Adjust environment settings warning to suggest upgrade - see [#795](https://github.com/chocolatey/choco/issues/795) -- API - Add the ability to retrieve package count for a Source - see [#431](https://github.com/chocolatey/choco/issues/431) -- API - Chocolatey Lib still marks vital package information as internal - see [#433](https://github.com/chocolatey/choco/issues/433) -- API - Add paging to list command - see [#427](https://github.com/chocolatey/choco/issues/427) -- API - Choco search should sort by version - see [#668](https://github.com/chocolatey/choco/issues/668) -- API - Switch dll to .NET Client Profile - see [#680](https://github.com/chocolatey/choco/issues/680) - -## [0.9.9.12](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.9.12+is%3Aclosed) (March 18, 2016) - -### Bug Fix - -- Fix - PowerShell "Collection is read-only" - see [#659](https://github.com/chocolatey/choco/issues/659) - -## [0.9.9.11](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.9.11+is%3Aclosed) (October 6, 2015) - -### Bug Fix - -- Fix - Pin list is broken - see [#452](https://github.com/chocolatey/choco/issues/452) - -## [0.9.9.10](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.9.10+is%3Aclosed) (October 3, 2015) - -Not to be confused with 0.9.10 (this is not that version). This fixes a small but extremely significant issue with relation to configuration managers and other tools that use choco. - -### Bug Fixes - -- Fix - List output for other tools messed up in 0.9.9.9 (pipe separator missing) - see [#450](https://github.com/chocolatey/choco/issues/450) -- Fix - accidentally escaped characters in "new" -help - see [#447](https://github.com/chocolatey/choco/issues/447) - -## [0.9.9.9](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.9.9+is%3Aclosed) (October 2, 2015) - -With this release you can completely configure choco from the command line (including the priority of sources). Choco now allows you to create [custom package templates](https://github.com/chocolatey/choco/issues/76). Choco has [proper proxy support](https://github.com/chocolatey/choco/issues/243) now. We also squashed up some bugs, like the infinite download loop that happens if the connection is lost. We've also improved the installation experience of Chocolatey itself, [unpacking all of the required setup files in the chocolatey package](https://github.com/chocolatey/choco/issues/347) and improving the messaging output during the bootstrapping process. Chocolatey also [doesn't try to write config updates every command](https://github.com/chocolatey/choco/issues/364), unless something actually changes in the config file. And last but not least for mentions, the issue of [choco not recognizing itself as needing upgraded after being installed by the bootstrapper](https://github.com/chocolatey/choco/issues/414) is now fixed. - -### Features - -- Config Command - see [#417](https://github.com/chocolatey/choco/issues/417) -- Create Custom Package Templates - see [#76](https://github.com/chocolatey/choco/issues/76) -- Proxy Support - see [#243](https://github.com/chocolatey/choco/issues/243) - -### Bug Fixes - -- Fix - [Security] Remove rollback should validate it exists in choco install backup directory - see [#387](https://github.com/chocolatey/choco/issues/387) -- Fix - Ensure chocolatey is installed into the lib folder during initial install - see [#414](https://github.com/chocolatey/choco/issues/414) -- Fix - Infinite loop downloading files if connection is lost - see [#285](https://github.com/chocolatey/choco/issues/285) -- Fix - list / search results blocking until completion instead of streaming output - see [#143](https://github.com/chocolatey/choco/issues/143) -- Fix - default template install script for MSI silentArgs are bad - see [#354](https://github.com/chocolatey/choco/issues/354) -- Fix - Deleting read-only files fails - see [#338](https://github.com/chocolatey/choco/issues/338) and [#263](https://github.com/chocolatey/choco/issues/263) -- Fix - If the package uses $packageParameters instead of $env:PackageParameters, quotes are removed - see [#406](https://github.com/chocolatey/choco/issues/406) -- Fix - Choco upgrade not downloading new installer if current installer is the same size - see [#405](https://github.com/chocolatey/choco/issues/405) -- Fix - Exit with non-zero code if install/upgrade version and a newer version is installed - see [#365](https://github.com/chocolatey/choco/issues/365) -- Fix - Chocolately can permanently corrupt the config file if an operation is interrupted - see [#355](https://github.com/chocolatey/choco/issues/355) -- Fix - Handle PowerShell's `InitializeDefaultDrives` Error (that should just be a warning) - see [#349](https://github.com/chocolatey/choco/issues/349) -- Fix - Checksumming can not be turned off by the feature flag - see [#33](https://github.com/chocolatey/choco/issues/33) -- Fix - Process with an id of is not running errors on 0.9.9.8 - see [#346](https://github.com/chocolatey/choco/issues/346) -- Fix - Export cmdlets for automation scripts - see [#422](https://github.com/chocolatey/choco/issues/422) - -### Improvements - -- [Security] Add SHA-2 (sha256 / sha512) to checksum - see [#113](https://github.com/chocolatey/choco/issues/113) -- Sources should have explicit priority order- see [#71](https://github.com/chocolatey/choco/issues/71) -- Unpack the powershell files just before packaging up the nupkg (Installing chocolatey meta) - see [#347](https://github.com/chocolatey/choco/issues/347) -- API - List --localonly not working by default - see [#223](https://github.com/chocolatey/choco/issues/223) -- API - Expose package results - see [#132](https://github.com/chocolatey/choco/issues/132) -- API - Externalize IPackage and its interfaces - see [#353](https://github.com/chocolatey/choco/issues/353) -- Enhance "Access to path is denied" message on no admin rights - see [#177](https://github.com/chocolatey/choco/issues/177) -- Only update chocolatey.config if there are changes - see [#364](https://github.com/chocolatey/choco/issues/364) -- Modify source when attempting to add a source with same name but different URL - see [#88](https://github.com/chocolatey/choco/issues/88) -- Features should contain description - see [#416](https://github.com/chocolatey/choco/issues/416) -- Chocolatey Installer - removing modules not loaded - see [#442](https://github.com/chocolatey/choco/issues/442) -- Chocolatey Installer - Don't use Write-Host - see [#444](https://github.com/chocolatey/choco/issues/444) -- Set environment variables once configuration is complete - see [#420](https://github.com/chocolatey/choco/issues/420) -- Enhance Package Template for 0.9.9.9 - see [#366](https://github.com/chocolatey/choco/issues/366) - -## [0.9.9.8](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.9.8+is%3Aclosed) (June 26, 2015) - -### Bug Fixes - -- Fix: choco install -y C: deletes all files - see [#341](https://github.com/chocolatey/choco/issues/341) -- Fix: Read-Host halts scripts rather than prompt for input - see [#219](https://github.com/chocolatey/choco/issues/219) - -### Improvement - -- Download Progress Bar is Missing - see [#56](https://github.com/chocolatey/choco/issues/56) - -## [0.9.9.7](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.9.7+is%3Aclosed) (June 20, 2015) - -"Fix Everything. Fix All The Things" - There have been some things bugging us for a long time related to limitations with NuGet, so we decided to fix that. Like [nuspec enhancements](https://github.com/chocolatey/choco/issues/205), that crazy [content folder restriction](https://github.com/chocolatey/choco/issues/290) has been removed (I know, right?!), and we're working around [badly](https://github.com/chocolatey/choco/issues/316) [behaved](https://github.com/chocolatey/choco/issues/326) packages quite a bit more to bring you more feature parity. - -Let's talk about a couple of big, like really big, BIG features just added with this release. No more packages rebooting Windows. We fixed ([#304](https://github.com/chocolatey/choco/issues/304) / [#323](https://github.com/chocolatey/choco/issues/323)) and [enhanced](https://github.com/chocolatey/choco/issues/305) up the Auto Uninstaller Service quite a bit to ensure things are working like you would expect (It goes on by default in 0.9.10 - we'll start documenting more about it soon). But wait, there's more! I haven't even told you about the big features yet - -The first big feature is enhancing the nuspec. I mentioned this I know, but *now* you can use `packageSourceUrl` in the nuspec to tell folks where you are storing the source for the package! We also added `projectSourceUrl`, `docsUrl`, `mailingListUrl`, and `bugTrackerUrl`. What's even better is that the community feed has already been enhanced to look for these values. So have the templates from `choco new`. And it's backwards compatible, meaning you can still install packages that have these added nuspec enhancements without issue (but we will need to provide a fix for Nuget Package Explorer). - -The second is Xml Document Transformations (XDT), which I think many folks are aware of but may not realize what it can provide. [NuGet has allowed transformations for quite awhile](https://docs.nuget.org/Create/Configuration-File-and-Source-Code-Transformations) to allow you to make changes to an `app.config`/`web.config` on install/uninstall. We are following in similar footsteps to allow you to do similar when installing/upgrading packages. We will look for `*.install.xdt` files in the package (doesn't matter where) and they will apply to configuration files with the same name in the package. This means that during upgrades we won't overwrite configuration files during upgrades that have opted into this feature. It allows you to give users a better experience during upgrades because they won't need to keep making the same changes to the xml config files each time they upgrade your package. - -### Features - -- Allow XDT Configuration Transforms - see [#331](https://github.com/chocolatey/choco/issues/331) -- Prevent reboots - see [#316](https://github.com/chocolatey/choco/issues/316) -- Enhance the nuspec - first wave - see [#205](https://github.com/chocolatey/choco/issues/205) -- Uninstaller Service Enhancements - see [#305](https://github.com/chocolatey/choco/issues/305) - -### Bug Fixes - -- When uninstall fails, do not continue removing files - see [#315](https://github.com/chocolatey/choco/issues/315) -- Do not run autouninstaller if the package result is already a failure - see [#323](https://github.com/chocolatey/choco/issues/323) -- Fix - Auto Uninstaller can fail if chocolateyUninstall.ps1 uninstalls prior to it running - see [#304](https://github.com/chocolatey/choco/issues/304) -- Fix - Packages with content folders cannot have a dependency without also having a content folder - see [#290](https://github.com/chocolatey/choco/issues/290) -- Remove ShimGen director files on upgrade/uninstall - see [#326](https://github.com/chocolatey/choco/issues/326) -- If feature doesn't exist, throw an error - see [#317](https://github.com/chocolatey/choco/issues/317) -- Fix - The operation completed successfully on stderr - see [#249](https://github.com/chocolatey/choco/issues/249) -- Fix - When specific nuget version is needed by a package it is the chocolatey version that is used - see [#194](https://github.com/chocolatey/choco/issues/194) -- When installing with *.nupkg, need to get package name from package, not file name - see [#90](https://github.com/chocolatey/choco/issues/90) -- Fix - Choco pin list is not returning a list - see [#302](https://github.com/chocolatey/choco/issues/302) -- Fix - A pin is not created for existing installations (prior to new choco) - see [#60](https://github.com/chocolatey/choco/issues/60) - -### Improvements - -- Allow upgrade to always install missing packages - see [#300](https://github.com/chocolatey/choco/issues/300) -- Enhance Templates - see [#296](https://github.com/chocolatey/choco/issues/296) -- Always log debug output to the log file - see [#319](https://github.com/chocolatey/choco/issues/319) -- Warn when unable to snapshot locked files - see [#313](https://github.com/chocolatey/choco/issues/313) -- Use %systemroot% in place of %windir%. PATH exceed 2048 breaks choco - see [#252](https://github.com/chocolatey/choco/issues/252) -- Add fault tolerance to registry snapshot checks - see [#337](https://github.com/chocolatey/choco/issues/337) - -## [0.9.9.6](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.9.6+is%3Aclosed) (May 16, 2015) - -Some really large fixes this release, especially removing all files that are installed to the package directory if they haven't changed, including ensuring that the nupkg file is always removed on successful uninstalls. The really big add some folks are going to like is the new outdated command. Some more variables that were misused have been brought back, which allows some packages (like Atom) to be installed again without issue. If you can believe some people never read these, we decided to add a note to the installer prompt to let people know about -y. - -### Feature - -- Outdated Command - Use `choco outdated` to see outdated packages - see [#170](https://github.com/chocolatey/choco/issues/170) - -### Bug Fixes - -- Fix - NotSilent Switch Not Working - see [#281](https://github.com/chocolatey/choco/issues/281) -- Fix - Silent installation of choco without admin is not possible - see [#274](https://github.com/chocolatey/choco/issues/274) -- Fix - Package resolves to latest version from any source - see [#279](https://github.com/chocolatey/choco/issues/279) -- Fix - Install fails when shortcut creation fails - see [#264](https://github.com/chocolatey/choco/issues/264) -- Fix - Error deserializing response of type Registry - see [#257](https://github.com/chocolatey/choco/issues/257) -- Fix - Auto uninstaller should not depend on optional InstallLocation value - see [#255](https://github.com/chocolatey/choco/issues/255) -- Fix - Nupkg is left but reported as successfully uninstalled by NuGet - see [#254](https://github.com/chocolatey/choco/issues/254) -- Fix - SHA1 checksum compared as MD5 for Install-ChocolateyZipPackage - see [#253](https://github.com/chocolatey/choco/issues/253) -- Fix - Auto uninstaller strips off "/" and "-" in arguments - see [#212](https://github.com/chocolatey/choco/issues/212) - -### Improvements - -- Uninstall removes all installed files if unchanged - see [#121](https://github.com/chocolatey/choco/issues/121) -- Auto uninstaller should convert /I to /X for Msi Uninstalls - see [#271](https://github.com/chocolatey/choco/issues/271) -- Bring back more variables for feature parity - see [#267](https://github.com/chocolatey/choco/issues/267) -- Mention -y in the prompt - see [#265](https://github.com/chocolatey/choco/issues/265) - -## [0.9.9.5](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.9.5+is%3Aclosed) (April 20, 2015) - -### Breaking Change - -- Renamed short option `p` to `i` for list --include-programs so that `p` could be ubiquitous for password across commands that optionally can pass a password - see [#240](https://github.com/chocolatey/choco/issues/240) - -### Bug Fixes - -- Fix - Secure Sources Not Working - see [#240](https://github.com/chocolatey/choco/issues/240) -- Fix - Generate-BinFile / Remove-BinFile - see [#230](https://github.com/chocolatey/choco/issues/230) -- Fix - cpack should only include files from nuspec - see [#232](https://github.com/chocolatey/choco/issues/232) -- Fix - cpack should leave nupkg in current directory - see [#231](https://github.com/chocolatey/choco/issues/231) -- Fix - Install-PowerShellCommand uses incorrect path - see [#241](https://github.com/chocolatey/choco/issues/241) -- Fix - choco list source with redirects does not resolve - see [#171](https://github.com/chocolatey/choco/issues/171) -- Fix - choco tried to resolve disabled repo - see [#169](https://github.com/chocolatey/choco/issues/169) -- Fix - cpack nuspec results in "The path is not of a legal form" - see [#164](https://github.com/chocolatey/choco/issues/164) -- Fix - cpack hangs on security related issue - see [#160](https://github.com/chocolatey/choco/issues/160) -- Fix - spelling error in "package has been upgradeed successfully" - see [#64](https://github.com/chocolatey/choco/issues/64) - -### Improvements - -- Api Key and Source matching could be more intuitive - see [#228](https://github.com/chocolatey/choco/issues/238) -- Remove warning about allowGlobalConfirmation being enabled - see [#237](https://github.com/chocolatey/choco/issues/237) -- Include log file path when saying 'See the log for details' - see [#187](https://github.com/chocolatey/choco/issues/187) -- Uninstall prompts for version when there is only one installed - see [#186](https://github.com/chocolatey/choco/issues/186) -- Do not offer a default option when prompting for a user choice - see [#185](https://github.com/chocolatey/choco/issues/185) -- Remove the warning note about skipping, and instead show the warning when selecting skip - see [#183](https://github.com/chocolatey/choco/issues/183) -- Do not print PowerShell install/update scripts by default - see [#182](https://github.com/chocolatey/choco/issues/182) - -## [0.9.9.4](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.9.4+is%3Aclosed) (March 30, 2015) - -### Bug Fix - -- Fix - The term 'false' is not recognized as the name of a cmdlet - see [#215](https://github.com/chocolatey/choco/issues/215) - -### Improvement - -- Some packages use non-API variables like $installArguments - see [#207](https://github.com/chocolatey/choco/issues/207) - -## [0.9.9.3](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.9.3+is%3Aclosed) (March 29, 2015) - -### Bug Fixes - -- Fix - Install .NET Framework immediately during install - see [#168](https://github.com/chocolatey/choco/issues/168) -- Fix - Do not error on Set-Acl during install/upgrade - see [#163](https://github.com/chocolatey/choco/issues/163) -- Fix - Do not escape curly braces in powershell script - see [#208](https://github.com/chocolatey/choco/issues/208) -- Fix - Formatting issues on --noop command logging - see [#202](https://github.com/chocolatey/choco/issues/202) -- Fix - Uninstaller check doesn't find 32-bit registry keys - see [#197](https://github.com/chocolatey/choco/issues/197) -- Fix - Uninstaller errors on short path to msiexec - see [#211](https://github.com/chocolatey/choco/issues/211) - -### Improvements - -- Some packages use non-API variables like $installArguments - see [#207](https://github.com/chocolatey/choco/issues/207) -- Add Generate-BinFile to Helpers (widely used but never part of API) - see [#145](https://github.com/chocolatey/choco/issues/145) -- Add Remove-BinFile to Helpers - see [#195](https://github.com/chocolatey/choco/issues/195) -- Get-ChocolateyWebFile should create path if it doesn't exist - see [#167](https://github.com/chocolatey/choco/issues/167) - -## [0.9.9.2](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.9.2+is%3Aclosed) (March 6, 2015) - -### Bug Fixes - -- Fix - Allow passing install arguments again (regression in 0.9.9 series) - see [#150](https://github.com/chocolatey/choco/issues/150) -- Fix - Allow apostrophes to be used as quotes - quoting style that worked with previous client - see [#141](https://github.com/chocolatey/choco/issues/141) -- Fix - Shims write errors to stderr - see [#142](https://github.com/chocolatey/choco/issues/142) and [ShimGen #14](https://github.com/chocolatey/shimgen/issues/14) - -### Improvement - -- Upgrade `-r` should always return a value - see [#153](https://github.com/chocolatey/choco/issues/153) - -## [0.9.9.1](https://github.com/chocolatey/choco/issues?q=milestone%3A0.9.9.1+is%3Aclosed) (March 3, 2015) - -### Bug Fix - -- Fix - Get-BinRoot broken - see [#144](https://github.com/chocolatey/choco/issues/144) - -## [0.9.9](https://github.com/chocolatey/choco/issues?q=is%3Aissue+milestone%3A0.9.9+is%3Aclosed) (March 3, 2015) - -This also includes issues that were being tracked in the old Chocolatey repository: [Chocolatey 0.9.9](https://github.com/chocolatey/chocolatey/issues?q=is%3Aclosed+label%3Av0.9.9). - -The two links above will not capture everything that has changed, since this is a complete rewrite. We broke everything. If this were a v1+, it would be a major release. But we are less than v1, so 0.9.9 it is! ;) - -Okay, so we didn't really break everything. We have maintained nearly full compatibility with how you pass options into choco, although the output may be a bit different (but better, we hope) and in at least one case, additional switches (or a feature setting) is/are required - we limited this to security related changes only. - -We also fixed and improved a bunch of things, so we feel the trade off is well worth the changes. - -We'll try to capture everything here that you should know about. Please call `choco -?` or `choco.exe -h` to get started. - -### Known Issues - -- [Known Issues](https://github.com/chocolatey/choco/labels/Bug) -- TEMPORARY `install all` is missing - this is expected to be back in 0.9.10 - see [#23](https://github.com/chocolatey/choco/issues/23) -- Alternative sources (`webpi`,`ruby`,`python`,`cygwin`, `windowsfeature`) do not work yet. This is expected to be fixed in 0.9.10 - see [#14](https://github.com/chocolatey/choco/issues/14) -- Progress bar is missing when downloading until we are using internal posh components for Packages - see [#56](https://github.com/chocolatey/choco/issues/56) -- See [Feature Parity](https://github.com/chocolatey/choco/labels/FeatureParity) for items not yet reimplemented from older PowerShell Chocolatey client (v0.9.8.32 and below). - -### Breaking Changes - -- [Security] **Prompt for confirmation**: For security reasons, we now stop for confirmation before changing the state of the system on most commands. You can pass `-y` to confirm any prompts **or set a value in the config that will globally confirm and behave like older versions of Chocolatey** - see [#52](https://github.com/chocolatey/choco/issues/52) - > :choco-info: **NOTE** - > - > This is one of those additional switches we were talking about) -- [Security] If your default installation is still at `c:\Chocolatey`, this version will force a move to ProgramData and update the environment settings - see [#7](https://github.com/chocolatey/choco/issues/7) -- **Configuration ### Breaking Changes** - 1. You now have one config file to interact with in %ChocolateyInstall%\config - your user config is no longer valid and can be removed once you migrate settings to the config. - 1. The config will no longer be overwritten on upgrade. - 1. Choco no longer interacts with NuGet's config file at all. You will need to reset all of your apiKeys (see features for `apikey`). On the plus side, the keys will work for all users of the machine, unlike NuGet's apiKeys (only work for the user that sets them). - 1. This also means you can no longer use `useNugetForSources`. It has been removed as a config setting. -- **Packaging Changes:** - 1. Choco now installs packages without version numbers on folders. This means quite a few things... - 1. Upgrading packages doesn't install a new version next to an old version, it actually upgrades. - 1. Dependencies resolve at highest available version, not the minimum version as before - see [Chocolatey #415](https://github.com/chocolatey/chocolatey/issues/415) - 1. `install` versus `upgrade` - Use `upgrade` on existing packages instead of install. A `-force` reinstall will reinstall the **same** version you already have installed. -- **Package Maintenance Changes**: - 1. Read the above about apikey changes - 1. Read above about dependency resolution changes. -- **Deprecated/Removed Commands:** - 1. `installmissing` has been removed. It was deprecated awhile ago, so this should not be a surprise. - 1. `choco version` has been deprecated and will be removed in v1. Use `choco upgrade pkgName --noop` or `choco upgrade pkgName -whatif` instead. - 1. `Write-ChocolateySuccess`, `Write-ChocolateyFailure` have been deprecated. - 1. `update` is now `upgrade`. `update` has been deprecated and will be removed/replaced in v1. Update will be reincarnated later for a different purpose. **Hint**: It rhymes with smackage pindexes. - -### Features - -- In app documentation! Use `choco -?`, `choco -h` or `choco commandName -?` to learn about each command, complete with examples! -- WhatIf/Noop mode for all commands (`--noop` can also be specified as `-whatif`) - see [Chocolatey #263](https://github.com/chocolatey/chocolatey/issues/263) and [Default Options and Switches](xref:choco-commands#default-options-and-switches) -- Performs like a package manager, expect to see queries failing because of unmet dependency issues. -- **New Commands:** - 1. `pin` - Suppress upgrades. This allows you to 'pin' an install to a particular version - see [#1](https://github.com/chocolatey/choco/issues/1), [Chocolatey #5](https://github.com/chocolatey/chocolatey/issues/5) and [Pin Command](xref:choco-command-pin) - 1. `apikey` - see [ApiKey Command](xref:choco-command-setapikey) - 1. `new` - see [New Command](xref:choco-command-new) and [Chocolatey #157](https://github.com/chocolatey/chocolatey/issues/157) -- New ways to pass arguments! See [How to Pass Options/Switches](xref:choco-commands#how-to-pass-options-switches) -- Did we mention there is a help menu that is actually helpful now? Shiny! -- AutoUninstaller!!!! But it is not enabled by default this version. See [#15](https://github.com/chocolatey/choco/issues/15), [#9](https://github.com/chocolatey/choco/issues/9) and [Chocolatey #6](https://github.com/chocolatey/chocolatey/issues/6) -- **New Helpers:** - 1. `Install-ChocolateyShortcut` - see [Chocolatey #238](https://github.com/chocolatey/chocolatey/pull/238), [Chocolatey #235](https://github.com/chocolatey/chocolatey/issues/235) and [Chocolatey #218](https://github.com/chocolatey/chocolatey/issues/218) - -### Bug Fixes - -Probably a lot of bug fixes that may not make it here, but here are the ones we know about. - -- Fix - Cannot upgrade from prerelease to same version released - see [Chocolatey #122](https://github.com/chocolatey/chocolatey/issues/122) -- Fix - install `--force` should not use cache - see [Chocolatey #199](https://github.com/chocolatey/chocolatey/issues/199) -- Fix - force dependencies as well - see [--force-dependencies](xref:choco-command-install) and [Chocolatey #199](https://github.com/chocolatey/chocolatey/issues/199) -- Fix - Chocolatey should not stop on error - see [Chocolatey #192](https://github.com/chocolatey/chocolatey/issues/192) -- Fix - Upgrading does not remove previous version - see [Chocolatey #259](https://github.com/chocolatey/chocolatey/issues/259) -- Fix - Non-elevated shell message spills errors - see [Chocolatey #540](https://github.com/chocolatey/chocolatey/issues/540) -- Fix - Package names are case sensitive for some sources - see [Chocolatey #589](https://github.com/chocolatey/chocolatey/issues/589) -- Fix - Install-ChocolateyVsixPackage doesn't check for correct VS 2012 path - see [Chocolatey #601](https://github.com/chocolatey/chocolatey/issues/601) -- Fix - Chocolatey behaves strangely after ctrl+c - see [Chocolatey #608](https://github.com/chocolatey/chocolatey/issues/608) -- Fix - Uninstall doesn't respect version setting - see [Chocolatey #612](https://github.com/chocolatey/chocolatey/issues/612) -- Fix - No update after download error - see [Chocolatey #637](https://github.com/chocolatey/chocolatey/issues/637) -- Fix - cup ends silently on error - see [Chocolatey #312](https://github.com/chocolatey/chocolatey/issues/312) -- Fix - cpack silently fails when dependency .NET 4.0+ is not met - see [Chocolatey #270](https://github.com/chocolatey/chocolatey/issues/270) -- Fix - Regression in cver all in 0.9.8.27 - see [Chocolatey #530](https://github.com/chocolatey/chocolatey/issues/530) -- Fix - Certain installs and updates fail with a "process with an Id of xxxx is not running" error - see [Chocolatey #603](https://github.com/chocolatey/chocolatey/issues/603) - -### Improvements - -- [Security] Allow keeping `c:\chocolatey` install directory with environment variable - see [#17](https://github.com/chocolatey/choco/issues/17) -- [Security] Require switch on unofficial build - see [#36](https://github.com/chocolatey/choco/issues/36) -- Install script updates - see [#7](https://github.com/chocolatey/choco/issues/7) -- Ensure Chocolatey pkg is installed properly in lib folder - This means you can take a dependency on a minimum version of Chocolatey (we didn't like that before) - see [#19](https://github.com/chocolatey/choco/issues/19) -- Uninstall - allow abort - see [#43](https://github.com/chocolatey/choco/issues/43) -- Support for HTTPS basic authorization - see [Chocolatey #128](https://github.com/chocolatey/chocolatey/issues/128) -- Smooth out success/failure logging - see [Chocolatey #154](https://github.com/chocolatey/chocolatey/issues/154) -- Add $env:CHOCOLATEY_VERSION - see [Chocolatey #251](https://github.com/chocolatey/chocolatey/issues/251) -- Replace ascii cue with visual cues - see [Chocolatey #376](https://github.com/chocolatey/chocolatey/pull/376) -- Uninstall all versions of an app - see [Chocolatey #389](https://github.com/chocolatey/chocolatey/issues/389) -- Add parameters in packages.config files - see [Packages.config](xref:choco-command-install#packagesconfig), [Chocolatey #472](https://github.com/chocolatey/chocolatey/issues/472), and [#10](https://github.com/chocolatey/choco/issues/10) -- Choco pack should support `-version` - see [Chocolatey #526](https://github.com/chocolatey/chocolatey/issues/526) -- Enhancements to Start-ChocolateyProcessAsAdmin - see [Chocolatey #564](https://github.com/chocolatey/chocolatey/pull/564) -- Install-ChocolateyFileAssociation - add label to new file types - see [Chocolatey #564](https://github.com/chocolatey/chocolatey/pull/564) -- Clean up the verobsity of Chocolatey - see [Chocolatey #374](https://github.com/chocolatey/chocolatey/issues/374) -- Compact choco upgrade --noop option - see [Chocolatey #414](https://github.com/chocolatey/chocolatey/issues/414) -- Remove references to the Chocolatey gods - see [Chocolatey #669](https://github.com/chocolatey/chocolatey/issues/669) -- Shims now have noop (`--shimgen-noop`) and help (`--shimgen-help`) switches - see [ShimGen #8](https://github.com/chocolatey/shimgen/issues/8) and [ShimGen #10](https://github.com/chocolatey/shimgen/issues/10) -- Shims will terminate underlying process on termination signal - see [ShimGen #11](https://github.com/chocolatey/shimgen/issues/11) -- Shims now have gui (`--shimgen-gui`) and exit (`--shimgen-exit`) switches - see [ShimGen #13](https://github.com/chocolatey/shimgen/issues/13) and [ShimGen #12](https://github.com/chocolatey/shimgen/issues/12) -- Dat help menu tho. I mean srsly guise - see [Chocolatey #641](https://github.com/chocolatey/chocolatey/issues/641) - -## [0.9.8.33](https://github.com/chocolatey/chocolatey/issues?q=label%3Av0.9.8.33+is%3Aclosed) (Feb 11, 2015) - -### Feature - -- Dynamically export helpers (this fixes helpers that were not visible before) - [#628](https://github.com/chocolatey/chocolatey/pull/628) - -### Improvements - -- Accept `-y` as a parameter, Add warning about -y for 0.9.9. -- Company name misspelled in shims - [#673](https://github.com/chocolatey/chocolatey/issues/673) and [shimgen #9](https://github.com/chocolatey/shimgen/issues/9) - -## [0.9.8.32](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.32&page=1&state=closed) (January 22, 2015) - -### Bug Fix - -- Fix - Chocolatey-Install should return non-zero exit code if chocolateyInstall.ps1 fails - [#568](https://github.com/chocolatey/chocolatey/issues/568) & [#658](https://github.com/chocolatey/chocolatey/pull/658) - -## [0.9.8.31](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.31&page=1&state=closed) (January 7, 2015) - -### Bug Fixes - -- Fix - Shim doesn't always shift off the first argument - [#655](https://github.com/chocolatey/chocolatey/issues/655) & [ShimGen #7](https://github.com/chocolatey/shimgen/issues/7) -- Fix - If executable isn't available, fallback to default icon - [#579](https://github.com/chocolatey/chocolatey/issues/579) - -## [0.9.8.30](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.30&page=1&state=closed) (January 6, 2015) - -### Feature - -- Use icon of the executable with generated shim - [#579](https://github.com/chocolatey/chocolatey/issues/579) & [ShimGen #2](https://github.com/chocolatey/shimgen/issues/2) - -### Bug Fix - -- Fix - Shims don't correctly handle spaces in path to shim - [#654](https://github.com/chocolatey/chocolatey/issues/654) & [ShimGen #5](https://github.com/chocolatey/shimgen/issues/5) - -## [0.9.8.29](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.29&page=1&state=closed) (January 2, 2015) - -### Features - -- Use icon of the executable with generated shim - [#579](https://github.com/chocolatey/chocolatey/issues/579) & [ShimGen #2](https://github.com/chocolatey/shimgen/issues/2) -- Allow setting custom temp download location - [#307](https://github.com/chocolatey/chocolatey/issues/307) - -### Improvements - -- Don't assume $env:TEMP or $env:UserProfile are set - [#647](https://github.com/chocolatey/chocolatey/issues/647) -- Remove Kickstarter message. - -## [0.9.8.28](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.28&page=1&state=closed) (November 4, 2014) - -### Breaking Change - -- You may need to update your saved API key for chocolatey, due to [#599](https://github.com/chocolatey/chocolatey/issues/599) we have switched push to ensure https. - -### Bug Fixes - -- Fix - Shim argument parsing needs fixed for quoting - [ShimGen #1](https://github.com/chocolatey/shimgen/issues/1) -- Fix - Forcing x86 does not use 32bit checksum - [#535](https://github.com/chocolatey/chocolatey/issues/535) -- Fix - Powershell v2 fails to download SSLv3 files - [#531](https://github.com/chocolatey/chocolatey/issues/531) -- Fix - Get-ChocolateyUnzip fails due to Wait-Process exception - [#571](https://github.com/chocolatey/chocolatey/issues/571) - -### Improvements - -- Use default credentials for internet if available - [#577](https://github.com/chocolatey/chocolatey/issues/577) -- Add moderation message on push - [#600](https://github.com/chocolatey/chocolatey/issues/600) -- Restrict all calls to chocolatey.org to HTTPS - [#599](https://github.com/chocolatey/chocolatey/issues/599) -- Batch fallback should quote path for spaces - [#558](https://github.com/chocolatey/chocolatey/issues/558) - -## [0.9.8.27](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.27&page=1&state=closed) (July 13, 2014) - -### Bug Fix - -- Fix - Posh v3+ Ignores -Wait when run from cmd.exe - [#516](https://github.com/chocolatey/chocolatey/pull/516) - -## [0.9.8.26](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.26&page=1&state=closed) (July 12, 2014) - -Pulled due to major breakage with #516 - -### Bug Fixes - -- Fix - Allow spaces in arguments to chocolatey again - Regenerate chocolatey included shims to take advantage of shimgen fixes - [#507](https://github.com/chocolatey/chocolatey/issues/507) -- Fix - Default path has changed, causing running without closing shell to have issues again - [#510](https://github.com/chocolatey/chocolatey/issues/510) -- Fix - Working directory of shimgen generated files points to path target executable is in (GUI apps only) - [#508](https://github.com/chocolatey/chocolatey/issues/508) -- Fix - cpack/cpush returns zero exit code even when error occurs - [#256](https://github.com/chocolatey/chocolatey/issues/256) & [#384](https://github.com/chocolatey/chocolatey/issues/384) -- Fix - Install error throws another error due to true instead of $true - [#514](https://github.com/chocolatey/chocolatey/pull/514) -- Fix - Posh v3+ Ignores -Wait when run from cmd.exe - [#516](https://github.com/chocolatey/chocolatey/pull/516) - -### Improvements - -- Allow to pass shimgen specific parameters - [#509](https://github.com/chocolatey/chocolatey/issues/509) -- Issue warning if user is not running an elevated shell - [#519](https://github.com/chocolatey/chocolatey/issues/519) - -## [0.9.8.25](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.25&page=1&state=closed) (July 7, 2014) - -### Bug Fixes - -- Fix - Shims that require admin may fail on UAC enforced machines (System.ComponentModel.Win32Exception: The requested operation requires elevation) - [#505](https://github.com/chocolatey/chocolatey/issues/505) -- Fix - Do not check content-length if there isn't a content-length returned from Get-WebHeaders - [#504](https://github.com/chocolatey/chocolatey/issues/504) - -## [0.9.8.24](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.24&page=1&state=closed) (July 3, 2014) - -### Breaking Changes - -- Enhancement - Default install to C:\ProgramData\chocolatey - [#452](https://github.com/chocolatey/chocolatey/issues/452) & [#494](https://github.com/chocolatey/chocolatey/issues/494) -- Don't allow $binroot to be set to c:\ - [#434](https://github.com/chocolatey/chocolatey/issues/434) - this is meant to be temporary while other pieces are fixed. - -### Features - -- Checksum downloaded files - [#427](https://github.com/chocolatey/chocolatey/issues/427) -- Replace Batch Redirector with Shims - [#372](https://github.com/chocolatey/chocolatey/issues/372) -- New Helper - Get-UACEnabled - [#451](https://github.com/chocolatey/chocolatey/issues/451) -- Enhancement - Install to Machine environment variable - [#453](https://github.com/chocolatey/chocolatey/issues/453) -- Enhancement - Install the .NET framework 4.0 requirement - [#255](https://github.com/chocolatey/chocolatey/issues/255) -- Update environment using command (RefreshEnv) - [#134](https://github.com/chocolatey/chocolatey/issues/134) -- `-quiet` parameter that silences almost all output / allow shutting off real write-host - [#416](https://github.com/chocolatey/chocolatey/pull/416) & [#411](https://github.com/chocolatey/chocolatey/issues/411) -- New Helpers - Test-ProcessAdminRights, Get-EnvironmentVariableNames, Get-EnvironmentVariable, Set-EnvironmentVariable - [#486](https://github.com/chocolatey/chocolatey/pull/486) - -### Bug Fixes - -- Fix - Cannot bind argument to parameter 'Path' because it is an empty string - [#371](https://github.com/chocolatey/chocolatey/issues/371) -- Fix - clist -source webpi doesn't prompt for admin access - [#293](https://github.com/chocolatey/chocolatey/issues/293) -- Fix - Get-ChocolateyUnzip silently fails due to incorrect usage of System32 (File System Redirector Issues) - [#476](https://github.com/chocolatey/chocolatey/pull/476) & [#455](https://github.com/chocolatey/chocolatey/issues/455) -- Fix - 7za.exe is subject to UAC file virtualization - [#454](https://github.com/chocolatey/chocolatey/issues/454) -- Fix - "You cannot call a method on a null-valued expression" introduced somewhere. - [#430](https://github.com/chocolatey/chocolatey/issues/430) -- Fix - Get-BinRoot defaulted to "C:\" instead of "C:\tools" - [#421](https://github.com/chocolatey/chocolatey/pull/421) -- Fix - Get-ProcessorBits doesn't return the bitness of the OperatingSystem - [#396](https://github.com/chocolatey/chocolatey/pull/396) -- Fix - Fix Invoke for Install All from a Feed (DEPRECATED by #446 - in improvements below) - [#381](https://github.com/chocolatey/chocolatey/issues/381) -- Fix - Upgrade to 0.9.8.24 produces cannot find Update-SessionEnvironment when using cmd.exe - [#459](https://github.com/chocolatey/chocolatey/issues/459) -- Fix - Package depending on newer chocolatey version is installed using existing version of chocolatey - [#460](https://github.com/chocolatey/chocolatey/issues/460) -- Fix - Bash improvements - [#383](https://github.com/chocolatey/chocolatey/pull/383) -- Fix - Resolve issue with DISM "missing" or with the 32-bit DISM being called on a 64-bit system - [#393](https://github.com/chocolatey/chocolatey/pull/393) -- Fix - Do NOT throw if missing a chocolateyuninstall.ps1 - [#499](https://github.com/chocolatey/chocolatey/issues/499) - -### Improvements - -- Do not download if file already cached - [#428](https://github.com/chocolatey/chocolatey/issues/428) & [#109](https://github.com/chocolatey/chocolatey/pull/109) -- If *.ignore file failes to create, do not fail the process - [#380](https://github.com/chocolatey/chocolatey/issues/380) -- Validate downloaded file is the right size - [#429](https://github.com/chocolatey/chocolatey/issues/429) -- Add perf to Chocolatey-List & allow to return as object - [#426](https://github.com/chocolatey/chocolatey/issues/426) -- Chocolatey-List LocalOnly performance improvements - [#425](https://github.com/chocolatey/chocolatey/pull/425) -- Chocolatey-Version Improvements - [#445](https://github.com/chocolatey/chocolatey/issues/445) -- Remove Invoke-Chocolatey Function to improve handling - [#446](https://github.com/chocolatey/chocolatey/issues/446) -- Don't create a window during Run-Nuget.ps1 - [#450](https://github.com/chocolatey/chocolatey/pull/450) -- Generate _env.cmd file instead of bat file for consistency - [#469](https://github.com/chocolatey/chocolatey/pull/469) -- Remove-BinFile removes shim.exes when installing a package - [#449](https://github.com/chocolatey/chocolatey/pull/449) -- Remove annoying "Reading environment variables from registry. Please wait..." - [#440](https://github.com/chocolatey/chocolatey/pull/440) -- Replace ascii cue to visual cue for "installing package" - [#376](https://github.com/chocolatey/chocolatey/pull/376) -- Clean up the verbosity of chocolatey - [#374](https://github.com/chocolatey/chocolatey/issues/374) -- Improve chocolatey setup as administrator - [#486](https://github.com/chocolatey/chocolatey/pull/486) -- Simplify Chocolatey-Update - [#493](https://github.com/chocolatey/chocolatey/issues/493) -- Update to Nuget.exe 2.8.2 - [#379](https://github.com/chocolatey/chocolatey/issues/379) - -## [0.9.8.23](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.23&page=1&state=closed) (November 11, 2013) - -### Bug Fixes - -- Fix - Chocolatey 0.9.8.22 incorrectly reports version as alpha1 [#368](https://github.com/chocolatey/chocolatey/issues/368) -- Fix - Some chocolatey commands with no arguments error [#369](https://github.com/chocolatey/chocolatey/issues/369) - -## [0.9.8.22](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.22&page=1&state=closed) (November 10, 2013) - -### Breaking Change - -- To use spaces and quotes, one should now use single quotation marks. It works best in both PowerShell and cmd. - -### Features - -- Enhancement - Add switch to force x86 when packages have both versions - [#365](https://github.com/chocolatey/chocolatey/issues/365) -- Enhancement - Allow passing parameters to packages - [#159](https://github.com/chocolatey/chocolatey/issues/159) - -### Bug Fix - -- Fix - Chocolatey 0.9.8.21 errors when using spaces or quotes with chocolatey or with batch redirect files [#367](https://github.com/chocolatey/chocolatey/issues/367) - -## [0.9.8.21](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.21&page=1&state=closed) (November 7, 2013) - -### Breaking Changes - -- Enhancement - For local package searching, use choco list -lo or choco search -lo. The execution speed is greatly increased. cver for local has been deprecated. - [#276](https://github.com/chocolatey/chocolatey/issues/276) -- Breaking - Chocolatey default sources no longer includes Nuget official feed. This will help improve response time and greatly increase relevant results. - [#349](https://github.com/chocolatey/chocolatey/issues/349) - -### Features - -- Enhancement - Support for Server Core - [#59](https://github.com/chocolatey/chocolatey/issues/59) -- Enhancement - Add a switch for ignoring dependencies on install `-ignoredependencies` - [#131](https://github.com/chocolatey/chocolatey/issues/131) -- Command - `choco` is now a default term -- Command - search is now a command (aliases list) `choco search something [-localonly]` -- Function - `Get-ProcessorBits` - tells you whether a processor is x86 or x64. This functionality was in chocolatey already but has been globalized for easy access. - [#231](https://github.com/chocolatey/chocolatey/issues/231) & [#229](https://github.com/chocolatey/chocolatey/issues/229) -- Function - `Get-BinRoot` - Gives package maintainers the ability to call one command that gets them the tools/bin root. This gives you the location where folks want certain packages installed. - [#359](https://github.com/chocolatey/chocolatey/pull/359) - -### Improvements - -- Enhancement - Install multiple packages by specifying them all on the same line - [#191](https://github.com/chocolatey/chocolatey/issues/191) -- Enhancement - Install .NET Framework 4.0 requirement if not already installed - [#255](https://github.com/chocolatey/chocolatey/issues/255) -- Enhancement - Refresh command line PATH after installs - partial to [#134](https://github.com/chocolatey/chocolatey/issues/134) - Previously we were just doing it in chocolatey with [#158](https://github.com/chocolatey/chocolatey/issues/158) -- Enhancement - Allow chocolatey to install when zip shell extensions are disabled - [#297](https://github.com/chocolatey/chocolatey/issues/297) -- Enhancement - Support for bash and similar shells - [#347](https://github.com/chocolatey/chocolatey/issues/347) & [#258](https://github.com/chocolatey/chocolatey/issues/258) -- Enhancement - Allow file uri to be used when downloading files - [#322](https://github.com/chocolatey/chocolatey/issues/322) -- Enhancement - Chocolatey version all versions returned for specific local package. - [#260](https://github.com/chocolatey/chocolatey/issues/260) -- Enhancement - Exit codes return appropriately - [#210](https://github.com/chocolatey/chocolatey/issues/210) -- Enhancement - Better logging support - [#208](https://github.com/chocolatey/chocolatey/issues/208) - -### Bug Fixes - -- Fix - Treat installation failures appropriately - [#10](https://github.com/chocolatey/chocolatey/issues/10) -- Fix - Using newer versions of nuget breaks chocolatey - [#303](https://github.com/chocolatey/chocolatey/issues/303) -- Fix - Chocolatey incorrectly reports 64 bit urls when downloading anything - [#331](https://github.com/chocolatey/chocolatey/issues/331) -- Fix - Executing `cuninst` without parameters shouldn't do anything - [#267](https://github.com/chocolatey/chocolatey/issues/267) & [#265](https://github.com/chocolatey/chocolatey/issues/265) -- Fix - VSIX installer helper is finding the wrong Visual Studio version - [#262](https://github.com/chocolatey/chocolatey/issues/262) -- Fix - Renaming logs appending `.old` results in error - [#225](https://github.com/chocolatey/chocolatey/issues/225) -- Fix - Minor typo in uninstall script "uninINstalling" - [#247](https://github.com/chocolatey/chocolatey/issues/247) -- Fix - Bug in Get-ChocolateyUnzip throws issues sometimes [#244](https://github.com/chocolatey/chocolatey/issues/244) & [#242](https://github.com/chocolatey/chocolatey/issues/242) -- Fix - Minor typo "succesfully" - [#241](https://github.com/chocolatey/chocolatey/issues/241) - - -## [0.9.8.20](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.20&page=1&state=closed) (December 11, 2012) - -### Features - -- Command - Win Feature feed - [#150](https://github.com/chocolatey/chocolatey/pull/150) -- Function - Add function to install environment variables - [#149](https://github.com/chocolatey/chocolatey/pull/149) -- Function - Function to associate file extensions with installed executables - [#146](https://github.com/chocolatey/chocolatey/pull/146) -- Function - Helper function to create explorer context menu items - [#144](https://github.com/chocolatey/chocolatey/pull/144) -- Function - Helper function for pinning items to task bar - [#143](https://github.com/chocolatey/chocolatey/pull/143) & [#141](https://github.com/chocolatey/chocolatey/pull/141) -- Command - Sources command - [#138](https://github.com/chocolatey/chocolatey/pull/138) -- Command - Provide a way to list all the installed packages - [#125](https://github.com/chocolatey/chocolatey/issues/125) - -### Improvements - -- Enhancement - Added FTP support for the chocolatey file downloader. - [#137](https://github.com/chocolatey/chocolatey/pull/137) -- Enhancement - Block installer exe from being "bin"-ed - [#174](https://github.com/chocolatey/chocolatey/issues/174) -- Enhancement - Making the unzip process silent - [#180](https://github.com/chocolatey/chocolatey/pull/180) -- Enhancement - Makes install args more explicit - [#179](https://github.com/chocolatey/chocolatey/pull/179) -- Enhancement - Update Write-Progress every 5000 iterations instead of every iteration - [#177](https://github.com/chocolatey/chocolatey/pull/177) -- Enhancement - Codeplex Support - [#176](https://github.com/chocolatey/chocolatey/issues/176) -- Enhancement - Fix downloads greater than 2GB - [#173](https://github.com/chocolatey/chocolatey/pull/173) -- Enhancement - Add -verbose switch for clist support to see package description - [#166](https://github.com/chocolatey/chocolatey/pull/166) -- Enhancement - Refresh env vars after Install - [#158](https://github.com/chocolatey/chocolatey/pull/158) & [#153](https://github.com/chocolatey/chocolatey/issues/153) -- Enhancement - Add EditorConfig file denoting coding style. - [#123](https://github.com/chocolatey/chocolatey/pull/123) -- Enhancement - Chocolatey-Version Remote Check - [#119](https://github.com/chocolatey/chocolatey/pull/119) -- Enhancement - Write every unzip path/file to a text file - [#114](https://github.com/chocolatey/chocolatey/pull/114) - -### Bug Fixes - -- Fix - "Execution of NuGet not detected" error. - [#151](https://github.com/chocolatey/chocolatey/pull/151) -- Fix - chocolatey.bat can't find chocolatey.cmd - [#152](https://github.com/chocolatey/chocolatey/issues/152) -- Fix - `chocolatey version all` prints only the last package's information - [#183](https://github.com/chocolatey/chocolatey/pull/183) -- Fix - Issue with $processor.addresswidth var - [#121](https://github.com/chocolatey/chocolatey/pull/121) - -## [0.9.8.19](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.19&page=1&state=closed) (July 2, 2012) - -### Feature - -- Enhancement - Allow community extensions - [#115](https://github.com/chocolatey/chocolatey/issues/115) - -### Bug Fixes - -- Fix - PowerShell v3 doesn't like foreach loop (prefers ForEach-Object) - [#116](https://github.com/chocolatey/chocolatey/pull/116) -- Fix - Cannot install Python packages on Windows 8 - [#117](https://github.com/chocolatey/chocolatey/issues/117) - -## [0.9.8.18](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.18&sort=created&direction=desc&state=closed&page=1) (June 16, 2012) - -### Bug Fix - -- Fix - 0.9.8.17 installer doesn't create chocolatey folder if it doesn't exist - [#112](https://github.com/chocolatey/chocolatey/issues/112) - -## [0.9.8.17](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.17&sort=created&direction=desc&state=closed&page=1) (June 15, 2012) - -### Feature - -- Enhancement - Support for naive uninstall - [#96](https://github.com/chocolatey/chocolatey/issues/96) - -### Improvements - -- Enhancement - Sources specified through config (or nuget.config) - [#101](https://github.com/chocolatey/chocolatey/pull/101) -- Enhancement - Chocolatey should support multiple sources - [#82](https://github.com/chocolatey/chocolatey/issues/82) -- Enhancement - Use Cygwin as a package source - [#93](https://github.com/chocolatey/chocolatey/pull/93) -- Enhancement - Use Python as a package source (uses easy_install) - [#100](https://github.com/chocolatey/chocolatey/issues/100) -- Enhancement - Use Default Credentials before Get-Credentials when using proxy on web call - [#83](https://github.com/chocolatey/chocolatey/pull/83) -- Enhancement - Reduce the verbosity of running chocolatey - [#84](https://github.com/chocolatey/chocolatey/issues/84) -- Enhancement - Support opening links to "GUI" type applications in a different way than the console apps - [#76](https://github.com/chocolatey/chocolatey/issues/76) -- Enhancement - Do not create batch redirects for certain executables in package folder - [#106](https://github.com/chocolatey/chocolatey/issues/106) -- Enhancement - Add a -debug switch - [#85](https://github.com/chocolatey/chocolatey/issues/85) -- Enhancement - Improve pipelining of cver by returning an object - [#94](https://github.com/chocolatey/chocolatey/pull/94) - -### Bug Fixes - -- Fix - Packages.config source now uses chocolatey/nuget sources by default instead of empty - [#79](https://github.com/chocolatey/chocolatey/issues/79) -- Fix - Executable batch links not created for "prerelease" versions - [#88](https://github.com/chocolatey/chocolatey/issues/88) -- Fix - Issue where latest version is not returned - [#92](https://github.com/chocolatey/chocolatey/pull/92) -- Fix - Prerelease versions now broken out as separate versions - [#90](https://github.com/chocolatey/chocolatey/issues/90) -- Fix - During install PowerShell session gets bad $env:ChocolateyInstall variable - [#80](https://github.com/chocolatey/chocolatey/issues/80) -- Fix - Build path with spaces now works - [#102](https://github.com/chocolatey/chocolatey/pull/102) - -## 0.9.8.16 (February 27, 2012) - -### Bug Fix - -- Small fix to installer for upgrade issues from 0.9.8.15 - -## [0.9.8.15](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.15&sort=created&direction=desc&state=closed&page=1) (February 27, 2012) - -### Breaking Changes - -- Enhancement - Chocolatey's default folder is now C:\Chocolatey (and no longer C:\NuGet) - [#58](https://github.com/chocolatey/chocolatey/issues/58) -- Enhancement - Use -force to reinstall existing packages - [#45](https://github.com/chocolatey/chocolatey/issues/45) - -### Feature - -- Enhancement - Install now supports **all** with a custom package source to install every package from a source! - [#46](https://github.com/chocolatey/chocolatey/issues/46) - -### Improvements - -- Enhancement - Support Prerelease flag for Install - [#71](https://github.com/chocolatey/chocolatey/issues/71) -- Enhancement - Support Prerelease flag for Update/Version - [#72](https://github.com/chocolatey/chocolatey/issues/72) -- Enhancement - Support Prerelease flag in List - [#74](https://github.com/chocolatey/chocolatey/issues/74) - -### Bug Fix - -- Fix - Parsing the wrong version when trying to update - [#73](https://github.com/chocolatey/chocolatey/issues/73) - -## [0.9.8.14](https://github.com/chocolatey/chocolatey/issues?labels=v0.9.8.14&sort=created&direction=desc&state=closed&page=1) (February 6, 2012) - -### Improvements - -- Enhancement - Pass ValidExitCodes to Install Helpers - [#54](https://github.com/chocolatey/chocolatey/issues/54) -- Enhancement - Add 64-bit url to Install-ChocolateyZipPackage - [#48](https://github.com/chocolatey/chocolatey/issues/48) -- Enhancement - Add 64-bit url to Install-ChocolateyPowershellCommand - [#57](https://github.com/chocolatey/chocolatey/issues/57) -- Enhancement - Make the main helpers work with files not coming over HTTP - [#51](https://github.com/chocolatey/chocolatey/issues/51) -- Enhancement - Upgrade NuGet.exe to 1.6.0 to take advantage of prerelease packaging - [#64](https://github.com/chocolatey/chocolatey/issues/64) - -### Bug Fixes - -- Fix - The packages.config feature has broken naming packages with '.config' - [#56](https://github.com/chocolatey/chocolatey/issues/56) -- Fix - CList includes all versions without adding the switch - [#60](https://github.com/chocolatey/chocolatey/issues/60) -- Fix - When NuGet.exe failes to run due to .NET Framework 4.0 not installed, chocolatey should report that. - [#65](https://github.com/chocolatey/chocolatey/issues/65) - -## [0.9.8.13](https://github.com/chocolatey/chocolatey/issues?labels=0.9.8.13&sort=created&direction=desc&state=closed&page=1) (January 8, 2012) - -### Features - -- New Command! Enhancement - Integration with Ruby Gems (`cgem packageName` or `cinst packageName -source ruby`) - [#29](https://github.com/chocolatey/chocolatey/issues/29) -- New Command! Enhancement - Integration with Web PI (`cwebpi packageName` or `cinst packageName -source webpi`) - [#28](https://github.com/chocolatey/chocolatey/issues/28) -- Enhancement - Call chocolatey install with packages.config file (thanks AnthonyMastrean!) - [#31](https://github.com/chocolatey/chocolatey/issues/31) and [#43](https://github.com/chocolatey/chocolatey/pull/43) and [#50](https://github.com/chocolatey/chocolatey/issues/50) -- New Command! Enhancement - Chocolatey Push (`chocolatey push packageName.nupkg` or `cpush packageName.nupkg`) - [#36](https://github.com/chocolatey/chocolatey/issues/36) -- New Command! Enhancement - Chocolatey Pack (`chocolatey pack [packageName.nuspec]` or `cpack [packageName.nuspec]`) - [#35](https://github.com/chocolatey/chocolatey/issues/35) - -### Improvements - -- Enhancement - @datachomp feature - Override Installer Arguments `chocolatey install packageName -installArgs "args to override" -override` or `cinst packageName -ia "args to override" -o`) - [#40](https://github.com/chocolatey/chocolatey/issues/40) -- Enhancement - @datachomp feature - Append Installer Arguments (`chocolatey install packageName -installArgs "args to append"` or `cinst packageName -ia "args to append"`) - [#39](https://github.com/chocolatey/chocolatey/issues/39) -- Enhancement - Run installer in not silent mode (`chocolatey install packageName -notSilent` or `cinst packageName -notSilent`) - [#42](https://github.com/chocolatey/chocolatey/issues/42) -- Enhancement - List available Web PI packages (`clist -source webpi`) - [#37](https://github.com/chocolatey/chocolatey/issues/37) -- Enhancement - List command should allow the All or AllVersions switch - [#38](https://github.com/chocolatey/chocolatey/issues/38) -- Enhancement - Any install will create the ChocolateyInstall environment variable so that installers can take advantage of it - [#30](https://github.com/chocolatey/chocolatey/issues/30) - -### Bug Fixes - -- Fixing an issue on proxy display message (Thanks jasonmueller!) - [#44](https://github.com/chocolatey/chocolatey/pull/44) -- Fixing the source path to allow for spaces (where chocolatey is installed) - [#33](https://github.com/chocolatey/chocolatey/issues/33) -- Fixing the culture to InvariantCulture to eliminate the turkish "I" issue - [#22](https://github.com/chocolatey/chocolatey/issues/22) - -## 0.9.8.12 (November 20, 2011) - -### Improvement - -- Enhancement - Reducing the number of window pop ups - [#25](https://github.com/chocolatey/chocolatey/issues/25) - -### Bug Fixes - -- Fixed an issue with write-host and write-error overrides that happens in the next version of PowerShell - [#24](https://github.com/chocolatey/chocolatey/pull/24) -- Fixing an issue that happens when PowerShell is not on the path - [#23](https://github.com/chocolatey/chocolatey/issues/23) -- Fixing the replacement of capital ".EXE" in addition to lowercase ".exe" when creating batch redirects - [#26](https://github.com/chocolatey/chocolatey/issues/26) - -## 0.9.8.11 (October 4, 2011) - -### Bug Fixes - -- Fixing an update issue if the package only exists on chocolatey.org - [#16](https://github.com/chocolatey/chocolatey/issues/16) -- Fixing an issue with install missing if the package never existed - [#13](https://github.com/chocolatey/chocolatey/issues/13) - -## 0.9.8.10 (September 17, 2011) - -### Feature - -- New Helper! Install-ChocolateyPowershellCommand - install a PowerShell script as a command - [#11](https://github.com/chocolatey/chocolatey/issues/11) - -## 0.9.8.9 (September 10, 2011) - -### Bug Fix - -- Reinstalls an existing package if -version (0.9.8.7+) or --version (>=0.9.9.0) is passed (first surfaced in 0.9.8.7 w/NuGet 1.5) - [#9](https://github.com/chocolatey/chocolatey/issues/9) - -## 0.9.8.8 (September 10, 2011) - -### Bug Fixes - -- Fixing version comparison - [#4](https://github.com/chocolatey/chocolatey/issues/4) -- Fixed package selector to not select like named packages (i.e. ruby.devkit when getting information about ruby) - [#3](https://github.com/chocolatey/chocolatey/issues/3) - -## 0.9.8.7 (September 2, 2011) - -### Improvements - -- Added proxy support based on [#1](https://github.com/chocolatey/chocolatey/issues/1) -- Updated to work with NuGet 1.5 - [#2](https://github.com/chocolatey/chocolatey/issues/2) - -## 0.9.8.6 (July 27, 2011) - -### Bug Fix - -- Fixed a bug introduced in 0.9.8.5 - Start-ChocolateyProcessAsAdmin erroring out when setting machine path as a result of trying to log the message. - -## 0.9.8.5 (July 27, 2011) - -### Improvements - -- Improving Run-ChocolateyProcessAsAdmin to allow for running entire functions as administrator by importing helpers to that command if using PowerShell. -- Updating some of the notes. - -### Bug Fix - -- Fixed bug in installer when User Environment Path is null. - -## 0.9.8.4 (July 27, 2011) - -### Bug Fix - -- Fixed a small issue with the Install-ChocolateyDesktopLink - -## 0.9.8.3 (July 7, 2011) - -### Breaking Change - -- Chocolatey no longer runs the entire PowerShell script as an administrator. With the addition of the Start-ChocolateyProcessAsAdmin, this is how you will get to administrative tasks outside of the helpers. - -### Features - -- New chocolatey command! InstallMissing allows you to install a package only if it is not already installed. Shortcut is 'cinstm'. -- New Helper! Install-ChocolateyPath - give it a path for out of band items that are not imported to path with chocolatey -- New Helper! Start-ChocolateyProcessAsAdmin - this allows you to run processes as administrator -- New Helper! Install-ChocolateyDesktopLink - put shortcuts on the desktop - -### Improvements - -- NuGet updated to v1.4 -- Much of the error handling is improved. There are two new Helpers to call (ChocolateySuccess and Write-ChocolateyFailure). -- Chocolatey no longer needs administrative rights to install itself. - -## 0.9.8.2 (May 21, 2011) - -### Feature - -- You now have the option of a custom installation folder. Thanks Jason Jarrett! - -## 0.9.8.1 (May 18, 2011) - -### Bug Fix - -- General fix to bad character in file. Fixed selection for update as well. - -## 0.9.8 (May 4, 2011) - -### Breaking Change - -- A dependency will not reinstall once it has been installed. To have it reinstall, you can install it directly (or delete it from the repository and run the core package). - -### Improvements - -- Shortcuts have been added: 'cup' for 'chocolatey update', 'cver' for 'chocolatey version', and 'clist' for 'chocolatey list'. -- Update only runs if newer version detected. -- Calling update with no arguments will update chocolatey. -- Calling update with all will update your entire chocolatey repository. - -## 0.9.7.3 (April 30, 2011) - -### Bug Fix - -- Fixing Install-ChocolateyZipPackage so that it works again. - -## 0.9.7.2 (April 29, 2011) - -### Bug Fix - -- Fixing an underlying issue with not having silent arguments for exe files. - -## 0.9.7.1 (April 29, 2011) - -### Bug Fixes - -- Fixing an introduced bug where the downloader didn't get the file name passed to it. - -## 0.9.7 (April 29, 2011) - -### Features - -- New helper added Install-ChocolateyInstallPackage - this was previously part of the download & install and has been broken out. -- New chocolatey command! Version allows you to see if a package you have installed is the most up to date. Leave out package and it will check for chocolatey itself. - -### Improvements - -- The PowerShell module is automatically loaded, so packages no longer need to import the module. This means one line chocolateyInstall.ps1 files! -- Error handling is improved. -- Silent installer override for msi has been removed to allow for additional arguments that need to be passed. - -## 0.9.6.4 (April 26, 2011) - -### Improvement - -- Remove PowerShell execution timeout. - -## 0.9.6.3 (April 25, 2011) - -### Feature - -- New Helper added Install-ChocolateyZipPackage - this wraps the two upper commands into one smaller command and addresses the file name bug. - -## 0.9.6.2 (April 25, 2011) - -### Bug Fix - -- Addressed a small bug in getting back the file name from the helper. - -## 0.9.6.1 (April 23, 2011) - -### Improvement - -- Adding in ability to find a dependency when the version doesn't exist. - -## 0.9.6 (April 23, 2011) - -### Improvement - -- Can execute PowerShell and chocolatey without having to change execution rights to PowerShell system wide. - -### Features - -- New Helper added - Get-ChocolateyWebFile - downloads a file from a url and gives you back the location of the file once complete. -- New Helper added - Get-ChocolateyZipContents - unzips a file to a directory of your choosing. - -## 0.9.5 (April 21, 2011) - -### Feature - -- Helper for native installer added (Install-ChocolateyPackage). Reduces the amount of PowerShell necessary to download and install a native package to two lines from over 25. - -### Improvements - -- Helper outputs progress during download. -- Dependency runner is complete. - -## 0.9.4 (April 10, 2011) - -### Improvements - -- List command has a filter. -- Package license acceptance terms notated. - -## 0.9.3 (April 4, 2011) - -### Improvement - -- You can now pass -source and -version (<0.9.9.0) or --version (>=0.9.9.0) to install command. - -## 0.9.2 (April 4, 2011) - -### Feature - -- List command added. - -## 0.9.1 (March 30, 2011) - -### Improvement - -- Shortcut for 'chocolatey install' - 'cinst' now available. diff --git a/input/en-us/choco/sensitive-inputs.md b/input/en-us/choco/sensitive-inputs.md deleted file mode 100644 index 7a7471b59e..0000000000 --- a/input/en-us/choco/sensitive-inputs.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -Order: 35 -xref: sensitive-inputs -Title: Sensitive Inputs -Description: Information on inputs that are hidden from the Chocolatey logs if detected ---- - -By default Chocolatey will omit logging commands or parameters that could potentially contain sensitive information. - -## Commands hidden from logs - -* `apikey` -* `config` -* `push` - -## Parameters hidden from logs - -* `--install-arguments-sensitive` -* `--package-parameters-sensitive` -* `-p` -* `--password` -* `-cp` -* `--certpassword` -* `-k` -* `--key` -* `--apikey` -* `--api-key` diff --git a/input/en-us/choco/setup.md b/input/en-us/choco/setup.md deleted file mode 100644 index d6c31582c2..0000000000 --- a/input/en-us/choco/setup.md +++ /dev/null @@ -1,912 +0,0 @@ ---- -Order: 20 -xref: setup-choco -Title: Setup / Install -Description: How to install Chocolatey CLI -RedirectFrom: - - docs/installation - - docs/install - - en-us/choco/installation ---- - -## Requirements - -- [A supported version of Windows](xref:chocolatey-components-dependencies-and-support-lifecycle#supported-windows-versions). -- [Supported version of PowerShell](xref:chocolatey-components-dependencies-and-support-lifecycle#supported-powershell-versions). - -### Chocolatey CLI v2.0+ - -- .NET Framework 4.8 - - The installation script will attempt to install .NET 4.8 if it is not installed. - -### Chocolatey CLI v1.x - -- .NET Framework 4+ - - The installation will attempt to install .NET 4.0 if you do not have it installed - - .NET Framework 4.5+ is required for installing directly from the Chocolatey Community Repository, due to the [TLS 1.2 requirement](https://blog.chocolatey.org/2020/01/remove-support-for-old-tls-versions/) - -## Installing Chocolatey CLI - -1. First, ensure that you are using an **[administrative shell](https://www.howtogeek.com/194041/how-to-open-the-command-prompt-as-administrator-in-windows-10/)**. - - Refer to [Non-Administrative Installation](#non-administrative-install) for information on installing without administrative rights. -1. Copy the text specific to your command shell - [cmd.exe](#install-with-cmd.exe) or [powershell.exe](#install-with-powershell.exe). -1. Paste the copied text into your shell and press Enter. -1. Wait a few seconds for the command to complete. -1. If you don't see any errors, you are ready to use Chocolatey CLI! -1. Type `choco` or `choco -?` now, or see [Getting Started](xref:getting-started) for usage instructions. - -> :choco-info: **NOTE** -> * If you are behind a proxy, please see Installing behind a proxy. -> * Need completely offline solution? See Completely Offline Install. -> * Installing the licensed edition? See [install licensed edition](xref:setup-licensed). -> * More Options / [Troubleshooting](xref:troubleshooting) - -#### Install with cmd.exe - -Run the following command: - -~~~sh - -@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin" - -~~~ - -#### Install with PowerShell.exe - -With PowerShell, there is an additional step. You must ensure [Get-ExecutionPolicy](https://go.microsoft.com/fwlink/?LinkID=135170) is not Restricted. We suggest using `Bypass` to bypass the policy to get things installed or `AllSigned` for quite a bit more security. - -* Run `Get-ExecutionPolicy`. If it returns `Restricted`, then run `Set-ExecutionPolicy AllSigned` or `Set-ExecutionPolicy Bypass -Scope Process`. -* Now run the following command: - -~~~powershell - -Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) - -~~~ - -#### Additional considerations - -> :choco-info: **NOTE** -> -> Please inspect [https://community.chocolatey.org/install.ps1](https://community.chocolatey.org/install.ps1) prior to running any of these scripts to ensure safety. We already know it's safe, but you should verify the security and contents of **any** script from the internet you are not familiar with. All of these scripts download a remote PowerShell script and execute it on your machine. - -We take security very seriously. [Learn more](xref:security). - -> "Why do I need to enable TLS 1.2 in PowerShell? Shouldn't it be on by default when I load PowerShell?" - -Unfortunately it's not always a default, and more of the time it is not. The low level is that it depends on .NET Framework and Windows. - -* Explicitly set - Basically you need .NET Fx 4.5 at a minimum to be able to explicitly set TLS 1.2. -* Load by default - To have it load by default when you run PowerShell, you need at least .NET Fx 4.7 AND the Operating System's SystemDefault to have TLS 1.2 enabled. - -The load by default is really hard to see, so you should check to ensure it is there. Assume it doesn't and set explicitly. - -## More Install Options - -**Troubleshooting? Proxy? Need more options?** - - - -
- -* [Install from PowerShell v3+](#install-from-powershell-v3) -* [Install using the MSI](#install-using-the-msi) -* [Install using WinGet](#install-using-winget) -* [Completely offline/internal install](#completely-offline-install) -* [Install with Puppet](#install-with-puppet) -* [Install using PowerShell from cmd.exe](#install-using-powershell-from-cmd.exe) -* [Install using NuGet Package Manager](#install-using-nuget-package-manager) -* [Install using NuGet.exe from PowerShell](#install-using-nuget.exe-from-powershell) -* [Install downloaded NuGet package from PowerShell](#install-downloaded-nuget-package-from-powershell) -* [Install licensed edition](#install-licensed-edition) -* [Installing behind a proxy](#installing-behind-a-proxy) -* [Installing behind an explicit proxy](#installing-behind-an-explicit-proxy) -* [Installing to a different location](#installing-to-a-different-location) -* [Installing a particular version of Chocolatey](#installing-a-particular-version-of-chocolatey) -* [Use Windows built-in compression instead of downloading 7zip](#use-windows-built-in-compression-instead-of-downloading-7zip) -* [Installing with restricted TLS](#installing-with-restricted-tls) -* [Non-Administrative install](#non-administrative-install) - -### Install from PowerShell v3+ - -> :choco-info: **NOTE** -> -> The command for installing with PowerShell at the top of the page works for all versions of PowerShell from v2 on. This is provided as an additional note for folks who want a more terse command that is easier to remember. - -With PowerShell, there is an additional step or two. You must ensure [Get-ExecutionPolicy](https://go.microsoft.com/fwlink/?LinkID=135170) is not Restricted. We suggest using `Bypass` to bypass the policy to get things installed or `AllSigned` for quite a bit more security. - -* Run `Get-ExecutionPolicy`. If it returns `Restricted`, then run `Set-ExecutionPolicy AllSigned` or `Set-ExecutionPolicy Bypass`. -* Now run the following command: - -~~~powershell - -Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iwr https://community.chocolatey.org/install.ps1 -UseBasicParsing | iex - -~~~ - -### Install using the MSI? - -From version 2.0.0 of Chocolatey CLI we provide an MSI for installation, allowing you to deploy using your existing tools. Once installed, use Chocolatey CLI as normal to upgrade. - -The MSI is provided as an asset on each GitHub release of Chocolatey CLI 2.0.0 onwards. See the assets section on the [Chocolatey GitHub repository release page](https://github.com/chocolatey/choco/releases). - -### Install using WinGet - -You can install Chocolatey CLI version 2.0.0 and later through WinGet by running `winget install --id chocolatey.chocolatey --source winget`. Once installed, use Chocolatey CLI as normal to upgrade. - -### Completely offline install - -With completely offline use of Chocolatey, you want to ensure you remove the default community package source (`choco source list` followed by `choco source remove --name chocolatey`, or however you would do that with a configuration manager [like Puppet](https://forge.puppet.com/puppetlabs/chocolatey#sources-configuration)). - -1. The first step with offline is to obtain a copy of the Chocolatey Nupkg (nupkg files are just fancy zip files). Go to https://community.chocolatey.org/packages/chocolatey and find a version you want. -1. Click on Download to download that version's nupkg file. - - ![download chocolatey.nupkg visual](/assets/images/DownloadChocolateyPackage.png) - -1. You can also download [the latest version directly](https://community.chocolatey.org/api/v2/package/chocolatey). -1. You can put the chocolatey.nupkg on an internal package repository and then address that full path, similar to how you see in the Puppet provider - https://forge.puppet.com/modules/puppetlabs/chocolatey/readme#manage-chocolatey-installation -1. Then you would run a script similar to the below to address that local install. If it is on a repository somewhere, you will need to enhance the below script to get that file (the Chocolatey Puppet provider install script shows that). - -~~~powershell -# Download and install Chocolatey nupkg from an OData (HTTP/HTTPS) url such as Artifactory, Nexus, ProGet (all of these are recommended for organizational use), or Chocolatey.Server (great for smaller organizations and POCs) -# This is where you see the top level API - with xml to Packages - should look nearly the same as https://community.chocolatey.org/api/v2/ -# If you are using Nexus, always add the trailing slash or it won't work -# === EDIT HERE === -$packageRepo = '' - -# If the above $packageRepo repository requires authentication, add the username and password here. Otherwise these leave these as empty strings. -$repoUsername = '' # this must be empty is NOT using authentication -$repoPassword = '' # this must be empty if NOT using authentication - -# Determine unzipping method -# 7zip is the most compatible, but you need an internally hosted 7za.exe. -# Make sure the version matches for the arguments as well. -# Built-in does not work with Server Core, but if you have PowerShell 5 -# it uses Expand-Archive instead of COM -$unzipMethod = 'builtin' -#$unzipMethod = '7zip' -#$7zipUrl = 'https://chocolatey.org/7za.exe' (download this file, host internally, and update this to internal) - -# === ENVIRONMENT VARIABLES YOU CAN SET === -# Prior to running this script, in a PowerShell session, you can set the -# following environment variables and it will affect the output - -# - $env:ChocolateyEnvironmentDebug = 'true' # see output -# - $env:chocolateyIgnoreProxy = 'true' # ignore proxy -# - $env:chocolateyProxyLocation = '' # explicit proxy -# - $env:chocolateyProxyUser = '' # explicit proxy user name (optional) -# - $env:chocolateyProxyPassword = '' # explicit proxy password (optional) - -# === NO NEED TO EDIT ANYTHING BELOW THIS LINE === -# Ensure we can run everything -Set-ExecutionPolicy Bypass -Scope Process -Force; - -# If the repository requires authentication, create the Credential object -if ((-not [string]::IsNullOrEmpty($repoUsername)) -and (-not [string]::IsNullOrEmpty($repoPassword))) { - $securePassword = ConvertTo-SecureString $repoPassword -AsPlainText -Force - $repoCreds = New-Object System.Management.Automation.PSCredential ($repoUsername, $securePassword) -} - -$searchUrl = ($packageRepo.Trim('/'), 'Packages()?$filter=(Id%20eq%20%27chocolatey%27)%20and%20IsLatestVersion') -join '/' - -# Reroute TEMP to a local location -New-Item $env:ALLUSERSPROFILE\choco-cache -ItemType Directory -Force -$env:TEMP = "$env:ALLUSERSPROFILE\choco-cache" - -$localChocolateyPackageFilePath = Join-Path $env:TEMP 'chocolatey.nupkg' -$ChocoInstallPath = "$($env:SystemDrive)\ProgramData\Chocolatey\bin" -$env:ChocolateyInstall = "$($env:SystemDrive)\ProgramData\Chocolatey" -$env:Path += ";$ChocoInstallPath" -$DebugPreference = 'Continue'; - -# PowerShell v2/3 caches the output stream. Then it throws errors due -# to the FileStream not being what is expected. Fixes "The OS handle's -# position is not what FileStream expected. Do not use a handle -# simultaneously in one FileStream and in Win32 code or another -# FileStream." -function Fix-PowerShellOutputRedirectionBug { - $poshMajorVerion = $PSVersionTable.PSVersion.Major - - if ($poshMajorVerion -lt 4) { - try{ - # http://www.leeholmes.com/blog/2008/07/30/workaround-the-os-handles-position-is-not-what-filestream-expected/ plus comments - $bindingFlags = [Reflection.BindingFlags] "Instance,NonPublic,GetField" - $objectRef = $host.GetType().GetField("externalHostRef", $bindingFlags).GetValue($host) - $bindingFlags = [Reflection.BindingFlags] "Instance,NonPublic,GetProperty" - $consoleHost = $objectRef.GetType().GetProperty("Value", $bindingFlags).GetValue($objectRef, @()) - [void] $consoleHost.GetType().GetProperty("IsStandardOutputRedirected", $bindingFlags).GetValue($consoleHost, @()) - $bindingFlags = [Reflection.BindingFlags] "Instance,NonPublic,GetField" - $field = $consoleHost.GetType().GetField("standardOutputWriter", $bindingFlags) - $field.SetValue($consoleHost, [Console]::Out) - [void] $consoleHost.GetType().GetProperty("IsStandardErrorRedirected", $bindingFlags).GetValue($consoleHost, @()) - $field2 = $consoleHost.GetType().GetField("standardErrorWriter", $bindingFlags) - $field2.SetValue($consoleHost, [Console]::Error) - } catch { - Write-Output 'Unable to apply redirection fix.' - } - } -} - -Fix-PowerShellOutputRedirectionBug - -# Attempt to set highest encryption available for SecurityProtocol. -# PowerShell will not set this by default (until maybe .NET 4.6.x). This -# will typically produce a message for PowerShell v2 (just an info -# message though) -try { - # Set TLS 1.2 (3072), then TLS 1.1 (768), then TLS 1.0 (192), finally SSL 3.0 (48) - # Use integers because the enumeration values for TLS 1.2 and TLS 1.1 won't - # exist in .NET 4.0, even though they are addressable if .NET 4.5+ is - # installed (.NET 4.5 is an in-place upgrade). - [System.Net.ServicePointManager]::SecurityProtocol = 3072 -bor 768 -bor 192 -bor 48 -} catch { - Write-Output 'Unable to set PowerShell to use TLS 1.2 and TLS 1.1 due to old .NET Framework installed. If you see underlying connection closed or trust errors, you may need to upgrade to .NET Framework 4.5+ and PowerShell v3+.' -} - -function Get-Downloader { -param ( - [string]$url - ) - $downloader = new-object System.Net.WebClient - - $defaultCreds = [System.Net.CredentialCache]::DefaultCredentials - if (Test-Path -Path variable:repoCreds) { - Write-Debug "Using provided repository authentication credentials." - $downloader.Credentials = $repoCreds - } elseif ($defaultCreds -ne $null) { - Write-Debug "Using default repository authentication credentials." - $downloader.Credentials = $defaultCreds - } - - $ignoreProxy = $env:chocolateyIgnoreProxy - if ($ignoreProxy -ne $null -and $ignoreProxy -eq 'true') { - Write-Debug 'Explicitly bypassing proxy due to user environment variable.' - $downloader.Proxy = [System.Net.GlobalProxySelection]::GetEmptyWebProxy() - } else { - # check if a proxy is required - $explicitProxy = $env:chocolateyProxyLocation - $explicitProxyUser = $env:chocolateyProxyUser - $explicitProxyPassword = $env:chocolateyProxyPassword - if ($explicitProxy -ne $null -and $explicitProxy -ne '') { - # explicit proxy - $proxy = New-Object System.Net.WebProxy($explicitProxy, $true) - if ($explicitProxyPassword -ne $null -and $explicitProxyPassword -ne '') { - $passwd = ConvertTo-SecureString $explicitProxyPassword -AsPlainText -Force - $proxy.Credentials = New-Object System.Management.Automation.PSCredential ($explicitProxyUser, $passwd) - } - - Write-Debug "Using explicit proxy server '$explicitProxy'." - $downloader.Proxy = $proxy - - } elseif (!$downloader.Proxy.IsBypassed($url)) { - # system proxy (pass through) - $creds = $defaultCreds - if ($creds -eq $null) { - Write-Debug 'Default credentials were null. Attempting backup method' - $cred = get-credential - $creds = $cred.GetNetworkCredential(); - } - - $proxyaddress = $downloader.Proxy.GetProxy($url).Authority - Write-Debug "Using system proxy server '$proxyaddress'." - $proxy = New-Object System.Net.WebProxy($proxyaddress) - $proxy.Credentials = $creds - $downloader.Proxy = $proxy - } - } - - return $downloader -} - -function Download-File { -param ( - [string]$url, - [string]$file - ) - $downloader = Get-Downloader $url - $downloader.DownloadFile($url, $file) -} - -function Download-Package { -param ( - [string]$packageODataSearchUrl, - [string]$file - ) - $downloader = Get-Downloader $packageODataSearchUrl - - Write-Output "Querying latest package from $packageODataSearchUrl" - [xml]$pkg = $downloader.DownloadString($packageODataSearchUrl) - $packageDownloadUrl = $pkg.feed.entry.content.src - - Write-Output "Downloading $packageDownloadUrl to $file" - $downloader.DownloadFile($packageDownloadUrl, $file) -} - -function Install-ChocolateyFromPackage { -param ( - [string]$chocolateyPackageFilePath = '' -) - - if ($chocolateyPackageFilePath -eq $null -or $chocolateyPackageFilePath -eq '') { - throw "You must specify a local package to run the local install." - } - - if (!(Test-Path($chocolateyPackageFilePath))) { - throw "No file exists at $chocolateyPackageFilePath" - } - - $chocTempDir = Join-Path $env:TEMP "chocolatey" - $tempDir = Join-Path $chocTempDir "chocInstall" - if (![System.IO.Directory]::Exists($tempDir)) {[System.IO.Directory]::CreateDirectory($tempDir)} - $file = Join-Path $tempDir "chocolatey.zip" - Copy-Item $chocolateyPackageFilePath $file -Force - - # unzip the package - Write-Output "Extracting $file to $tempDir..." - if ($unzipMethod -eq '7zip') { - $7zaExe = Join-Path $tempDir '7za.exe' - if (-Not (Test-Path ($7zaExe))) { - Write-Output 'Downloading 7-Zip commandline tool prior to extraction.' - # download 7zip - Download-File $7zipUrl "$7zaExe" - } - - $params = "x -o`"$tempDir`" -bd -y `"$file`"" - # use more robust Process as compared to Start-Process -Wait (which doesn't - # wait for the process to finish in PowerShell v3) - $process = New-Object System.Diagnostics.Process - $process.StartInfo = New-Object System.Diagnostics.ProcessStartInfo($7zaExe, $params) - $process.StartInfo.RedirectStandardOutput = $true - $process.StartInfo.UseShellExecute = $false - $process.StartInfo.WindowStyle = [System.Diagnostics.ProcessWindowStyle]::Hidden - $process.Start() | Out-Null - $process.BeginOutputReadLine() - $process.WaitForExit() - $exitCode = $process.ExitCode - $process.Dispose() - - $errorMessage = "Unable to unzip package using 7zip. Perhaps try setting `$env:chocolateyUseWindowsCompression = 'true' and call install again. Error:" - switch ($exitCode) { - 0 { break } - 1 { throw "$errorMessage Some files could not be extracted" } - 2 { throw "$errorMessage 7-Zip encountered a fatal error while extracting the files" } - 7 { throw "$errorMessage 7-Zip command line error" } - 8 { throw "$errorMessage 7-Zip out of memory" } - 255 { throw "$errorMessage Extraction cancelled by the user" } - default { throw "$errorMessage 7-Zip signalled an unknown error (code $exitCode)" } - } - } else { - if ($PSVersionTable.PSVersion.Major -lt 5) { - try { - $shellApplication = new-object -com shell.application - $zipPackage = $shellApplication.NameSpace($file) - $destinationFolder = $shellApplication.NameSpace($tempDir) - $destinationFolder.CopyHere($zipPackage.Items(),0x10) - } catch { - throw "Unable to unzip package using built-in compression. Set `$env:chocolateyUseWindowsCompression = 'false' and call install again to use 7zip to unzip. Error: `n $_" - } - } else { - Expand-Archive -Path "$file" -DestinationPath "$tempDir" -Force - } - } - - # Call Chocolatey install - Write-Output 'Installing chocolatey on this machine' - $toolsFolder = Join-Path $tempDir "tools" - $chocInstallPS1 = Join-Path $toolsFolder "chocolateyInstall.ps1" - - & $chocInstallPS1 - - Write-Output 'Ensuring chocolatey commands are on the path' - $chocInstallVariableName = 'ChocolateyInstall' - $chocoPath = [Environment]::GetEnvironmentVariable($chocInstallVariableName) - if ($chocoPath -eq $null -or $chocoPath -eq '') { - $chocoPath = 'C:\ProgramData\Chocolatey' - } - - $chocoExePath = Join-Path $chocoPath 'bin' - - if ($($env:Path).ToLower().Contains($($chocoExePath).ToLower()) -eq $false) { - $env:Path = [Environment]::GetEnvironmentVariable('Path',[System.EnvironmentVariableTarget]::Machine); - } - - Write-Output 'Ensuring chocolatey.nupkg is in the lib folder' - $chocoPkgDir = Join-Path $chocoPath 'lib\chocolatey' - $nupkg = Join-Path $chocoPkgDir 'chocolatey.nupkg' - if (!(Test-Path $nupkg)) { - Write-Output 'Copying chocolatey.nupkg is in the lib folder' - if (![System.IO.Directory]::Exists($chocoPkgDir)) { [System.IO.Directory]::CreateDirectory($chocoPkgDir); } - Copy-Item "$file" "$nupkg" -Force -ErrorAction SilentlyContinue - } -} - -# Idempotence - do not install Chocolatey if it is already installed -if (!(Test-Path $ChocoInstallPath)) { - # download the package to the local path - if (!(Test-Path $localChocolateyPackageFilePath)) { - Download-Package $searchUrl $localChocolateyPackageFilePath - } - - # Install Chocolatey - Install-ChocolateyFromPackage $localChocolateyPackageFilePath -} - -~~~ - -### Install with Puppet - -> :choco-info: **NOTE** -> -> If you have the licensed edition, see [Setting up Licensed Edition with Puppet](xref:setup-licensed#set-up-licensed-edition-with-puppet) instead. This only additionally contains some package examples and setting up tab completion. - -Here's an example of setting Chocolatey up with Puppet that sets up and configures Chocolatey, sets up an internal package repository, and shows setting up the licensed edition and ensuring some packages. - -* Download the chocolatey.nupkg from the community repository - [download the latest chocolatey nupkg](https://community.chocolatey.org/api/v2/package/chocolatey) or see [Completely offline install](#completely-offline-install) to get an older version. -* Optionally download the chocolatey.server package from the community repository - [download the latest chocolatey.server nupkg](https://community.chocolatey.org/api/v2/package/chocolatey.server). -* Use `choco push` to push those items to your internal package repository (e.g. `choco push chocolatey.0.10.7.nupkg --source http://internal_repo/ --api-key abc123`) -* Determine how to get the bare url to download the Chocolatey.Nupkg directly. You will need that for the internal url for installing Chocolatey offline. For the community repository, it is https://community.chocolatey.org/api/v2/package/chocolatey - - -~~~puppet -# Requires puppetlabs/chocolatey module -# See https://forge.puppet.com/puppetlabs/chocolatey - -## Set resource defaults for `package` resources on Windows to use the Chocolatey provider -case $operatingsystem { - 'windows': { - Package { - provider => chocolatey, - } - } -} - -## - Ensure Chocolatey Install - -#include chocolatey -## OR -## Download chocolatey.nupkg to your internal repository (see above -## about getting the package for offline use) -## Note: `chocolatey_download_url is completely different than normal -## source locations. This is directly to the bare download url for the -## chocolatey.nupkg, similar to what you see when you browse to -## https://community.chocolatey.org/api/v2/package/chocolatey -class {'chocolatey': - chocolatey_download_url => 'https:///chocolatey.nupkg', - use_7zip => false, -} - -## If you need FIPS compliance -## make this the first thing you configure before you do any additional -## configuration or package installations -#chocolateyfeature {'useFipsCompliantChecksums': -# ensure => enabled, -#} - -## Keep chocolatey up to date based on your internal source -## You control the upgrades based on when you push an updated version -## to your internal repository. -## Note the source here is to the OData feed, similar to what you see -## when you browse to https://chocolatey.org/api/v2 -package {'chocolatey': - ensure => latest, - provider => chocolatey, - source => 'https:///chocolatey', -} - - -## - Configure Chocolatey - -### Config Settings - -## Move cache location so Chocolatey is very deterministic about -## cleaning up temporary data -chocolateyconfig {'cacheLocation': - value => 'c:\ProgramData\chocolatey\choco-cache', -} - -## Increase timeout to 4 hours -chocolateyconfig {'commandExecutionTimeoutSeconds': - value => '14400', -} - -### Sources -## Remove the default community package repository source -chocolateysource {'chocolatey': - ensure => absent, - location => 'https://community.chocolatey.org/api/v2/', -} - -## Add default sources for your internal repositories -chocolateysource {'internal_chocolatey': - ensure => present, - location => 'http://internal_location/OData/endpoint', - priority => 1, - username => 'optional', - password => 'optional,not ensured', -} - -### Features -chocolateyfeature {'checksumFiles': - ensure => enabled, -} - -## When using Puppet for installs -chocolateyfeature {'showDownloadProgress': - ensure => disabled, -} - -chocolateyfeature {'useRememberedArgumentsForUpgrades': - ensure => enabled, -} - - -## - Chocolatey Simple Server Package Repository - -## Requires chocolatey/chocolatey_server module - see -## https://forge.puppet.com/chocolatey/chocolatey_server -## this contains the bits to install the custom server -## - Ensures IIS and Ensure ASP.NET -## - Installs and configures the Chocolatey.Server website and app pool -## - Sets permissions appropriately - -#include chocolatey_server -## OR -## `server_package_source` is to the OData feed, similar to what you see -## when you browse to https://chocolatey.org/api/v2 -class {'chocolatey_server': - server_package_source => 'https://internalurl/odata/server', -} - -chocolateysource {'local_chocolatey_server': - ensure => present, - location => 'http://localhost/chocolatey', - priority => 2, -} - - -## - Tab Completion - -## Ensure that when someone uses choco from powershell.exe, they have tab completion -file {'C:/Users/Administrator/Documents/WindowsPowerShell': - ensure => directory, -} - -file {'C:/Users/Administrator/Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1': - ensure => file, - content => '$ChocolateyProfile = "$env:ChocolateyInstall\helpers\chocolateyProfile.psm1" -if (Test-Path($ChocolateyProfile)) { - Import-Module "$ChocolateyProfile" -}', -} - - -## - Package Examples - -package {'roundhouse': - ensure => '0.8.5.0', -} - -package {'git': - ensure => latest, -} - -## see https://forge.puppet.com/puppetlabs/chocolatey#install-options-with-spaces -package {'launchy': - ensure => installed, - install_options => ['--override', '--installArgs','"', '/VERYSILENT','/NORESTART','"'], -} - -package {['virustotaluploader', - 'googlechrome', - 'notepadplusplus', - '7zip', - 'ruby', - 'charles', - 'grepwin', - 'stexbar', - 'inkscape', - 'gitextensions', - 'pandoc', - 'snagit', - 'nodejs', - ]: - ensure => latest, - source => 'https://community.chocolatey.org/api/v2/', -} - -package {'screentogif': - ensure => '2.2.160907', - source => 'https://community.chocolatey.org/api/v2/', -} - -package {'dotnet4.5.2': - ensure => latest, -} -~~~ - -### Install using PowerShell from cmd.exe - -This is the best method if you want to repeat it or include it in source control. It requires no change to your existing PowerShell to allow for remote unsigned scripts. - -Create a file named `installChocolatey.cmd` with the following: - -~~~ -@echo off - -SET DIR=%~dp0% - -::download install.ps1 -%systemroot%\System32\WindowsPowerShell\v1.0\powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "((new-object net.webclient).DownloadFile('https://community.chocolatey.org/install.ps1','%DIR%install.ps1'))" -::run installer -%systemroot%\System32\WindowsPowerShell\v1.0\powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "& '%DIR%install.ps1' %*" -~~~ - -You can also get to this file by going to [https://community.chocolatey.org/installChocolatey.cmd](https://community.chocolatey.org/installChocolatey.cmd). - -If you prefer to have the install.ps1 file already, comment out the download line in the batch file and download the [`install.ps1`](https://community.chocolatey.org/install.ps1) from [community.chocolatey.org](https://community.chocolatey.org/install.ps1) and save it as `install.ps1` next to the `installChocolatey.cmd` file. - -Run `installChocolatey.cmd` from an elevated `cmd.exe` command prompt and it will install the latest version of Chocolatey. You can not run this from `powershell.exe` without making changes to your execution policy. - -> :choco-info: **NOTE** -> -> To create and save a `.cmd` file, please use a text editor and nothing fancy like Microsoft Word or OneNote. - -### Install using NuGet Package Manager - -When you have Visual Studio 2010+ and the NuGet extension installed (pre-installed on any newer versions of Visual Studio), you can simply type the following three commands and you will have Chocolatey installed on your machine. - - `Install-Package chocolatey` - `Initialize-Chocolatey` - `Uninstall-Package chocolatey` - -### Install using NuGet.exe from PowerShell - -You can also use NuGet command line to download Chocolatey: - - `nuget install chocolatey` or `nuget install chocolatey -pre` - -Once you download it, open PowerShell (remote unsigned), navigate to the tools folder and run: - -`& .\chocolateyInstall.ps1` - -### Install downloaded NuGet package from PowerShell - -You can also just download and unzip the Chocolatey package (`.nupkg` is a fancy zip file): - - 1. Download the [Chocolatey package](https://community.chocolatey.org/api/v2/package/chocolatey/). - 1. Ensure the downloaded nupkg is not blocked. - 1. Unzip it using any application that supports `zip` format. - 1. Open a PowerShell command shell and navigate into the unzipped package's tools folder. - > :choco-info: **NOTE** - > - > Ensure PowerShell execution policy is set to at least bypass or remote signed (if you have issues, you may need to set it to Unrestricted). - 1. Call `& .\chocolateyInstall.ps1` to allow Chocolatey to install. - > :choco-info: **NOTE** - > - > This will not set Chocolatey as an installed package, so it may be a good idea to also call `choco upgrade chocolatey -y` and let it reinstall the same version, but at least it will be available for upgrades then. - -### Install licensed edition - -Please see [installation of licensed edition](xref:setup-licensed). - -### Installing behind a proxy - -Have a proxy? Try - -* Cmd.exe: - -~~~sh - -@powershell -NoProfile -ExecutionPolicy Bypass -Command "[System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultCredentials; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))" && SET PATH="%PATH%;%ALLUSERSPROFILE%\chocolatey\bin" - -~~~ - -* PowerShell.exe (Ensure [Get-ExecutionPolicy](https://go.microsoft.com/fwlink/?LinkID=135170) is at least RemoteSigned): - -~~~powershell - -[System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultCredentials; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) - -~~~ - -### Installing behind an explicit proxy - -See [Installing Chocolatey Behind a Proxy Server](xref:proxy-settings#installing-chocolatey-behind-a-proxy-server) - -### Installing to a different location - -1. Create a __machine__ level (__user__ level will also work) environment variable named ```ChocolateyInstall``` and set it to the folder you want Chocolatey to install to prior to installation (this environment variable must be set globally or available to PowerShell- it is not enough to simply make it available to your current command prompt session). -1. Don't use `"C:\Chocolatey"` unless necessary. -1. Create the folder manually. -1. If you have already installed (and want to change the location after the fact): - * Follow the above steps. - * Install Chocolatey again. - * Copy/Move over the items from the old lib/bin directory. - * Delete your old install directory. - -> :choco-info: **NOTE** -> -> There is one really important consideration when installing Chocolatey to a non-default location: Chocolatey only locks down the permissions to Admins when installed to the default location `%PROGRAMDATA%\Chocolatey`, which means the same thing as `%SystemDrive%\ProgramData\Chocolatey`. -> If you are installing to another location, you will need to handle this yourself, i. e. restrict write access to Admins in case you so desire. -This is due to alternative locations could have a range of permissions that should not be changed. -See [Why does Chocolatey install where it does](xref:default-chocolatey-install-reasoning) and [GitHub Issue 398](https://github.com/chocolatey/choco/issues/398) for more details. - -### Installing a particular version of Chocolatey - -Set the following environment variable prior to install: - -* `chocolateyVersion` - controls what version of Chocolatey is installed - -In PowerShell, it looks like this: - -~~~powershell -$env:chocolateyVersion = '0.9.9.12' -# install script -~~~ - -> :choco-info: **NOTE** -> -> This will only work with the installation methods that call https://community.chocolatey.org/install.ps1 as part of the install. - -### Use Windows built-in compression instead of downloading 7zip - -Set the following environment variable prior to install: - -* `chocolateyUseWindowsCompression` - this will bypass the download and use of 7zip. - -In PowerShell, it looks like this: - -~~~powershell -$env:chocolateyUseWindowsCompression = 'true' -# install script -~~~ - -> :choco-info: **NOTE** -> -> This will only work with the installation methods that call https://community.chocolatey.org/install.ps1 as part of the install. - -### Installing with restricted TLS - -> :choco-info: **NOTE** -> -> community.chocolatey.org now requires TLS 1.2 at a minimum. Please see https://blog.chocolatey.org/2020/01/remove-support-for-old-tls-versions/. - -> :choco-info: **NOTE** -> -> If your server is restricted to TLS 1.1+, you need to add additional logic to be able to download and install Chocolatey (this is not necessary when running Chocolatey normally as it does this automatically). - -> :choco-info: **NOTE** -> -> If this is for organizational use, you should consider hosting the Chocolatey package internally and installing from there. - - -If you see an error that looks similar to the following: - -~~~sh -Exception calling "DownloadString" with "1" argument(s): "The underlying connection was closed: An unexpected error -occurred on a receive." -At line:1 char:1 -+ iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/in ... -+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - + CategoryInfo : NotSpecified: (:) [], MethodInvocationException - + FullyQualifiedErrorId : WebException -~~~ - -OR: - -~~~sh -Exception calling "DownloadString" with "1" argument(s): "The request was aborted: Could not create SSL/TLS secure -channel." -At line:1 char:51 -+ ... ess -Force; iex ((New-Object System.Net.WebClient).DownloadString('ht ... -+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - + CategoryInfo : NotSpecified: (:) [], MethodInvocationException - + FullyQualifiedErrorId : WebException -~~~ - -It's possible that you are attempting to install from a server that needs to use TLS 1.1 or TLS 1.2 (has restricted the use of TLS 1.0 and SSL v3), you have some options. community.chocolatey.org now requires TLS 1.2 at a minimum. - -#### Option 1 - Host Internally - -If you are an organization, this is your best option and it reduces issues with rate limiting that could occur later. - -See https://chocolatey.org/install#organization for details. - - -#### Option 2 - Updated PowerShell and .NET - -Upgrade to the following: - -* [A supported PowerShell version](xref:chocolatey-components-dependencies-and-support-lifecycle#supported-powershell-versions) -* .NET Framework 4.5 - -~~~powershell -try { - # Set TLS 1.2 (3072) as that is the minimum required by Chocolatey.org - # Use integers because the enumeration value for TLS 1.2 won't exist - # in .NET 4.0, even though they are addressable if .NET 4.5+ is - # installed (.NET 4.5 is an in-place upgrade). - [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072 -} catch { - Write-Warning 'Unable to set PowerShell to use TLS 1.2. This is required for contacting Chocolatey as of 03 FEB 2020. https://blog.chocolatey.org/2020/01/remove-support-for-old-tls-versions/. If you see underlying connection closed or trust errors, you may need to do one or more of the following: (1) upgrade to .NET Framework 4.5+ and PowerShell v3+, (2) Call [System.Net.ServicePointManager]::SecurityProtocol = 3072; in PowerShell prior to attempting installation, (3) specify internal Chocolatey package location (set $env:chocolateyDownloadUrl prior to install or host the package internally), (4) use the Download + PowerShell method of install. See https://docs.chocolatey.org/en-us/choco/setup for all install options.' -} - -iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) -~~~ - -#### Option 3 - Manual - -You need to download and unzip the Chocolatey package, then call the PowerShell install script from there. See the [Install downloaded NuGet package from PowerShell](#install-downloaded-nuget-package-from-powershell) section below. - - -### Non-Administrative install - -> :choco-info: **NOTE** -> -> This option should be a last resort and is considered to be a more advanced scenario - most things you do on Windows require administrative rights, especially surrounding software management, so you are going to be limited even in packages you attempt to install. If you are using the [community package repository](https://community.chocolatey.org/packages), there are over 200 packages you can install from the community repository without administrative permission - see https://community.chocolatey.org/packages?q=id%3Aportable+tag%3Aportable. - -You must choose a different location than the default (see [Installing to a different location](#installing-to-a-different-location) above). The default is a more secure location that only administrators can update. - -1. Save the script below as `ChocolateyInstallNonAdmin.ps1`. -1. Use the script below, determine where you might want Chocolatey installed if it is not to `C:\ProgramData\chocoportable`. -1. Open PowerShell.exe. -1. Run the following `Set-ExecutionPolicy Bypass -Scope Process -Force;` -1. Run `.\ChocolateyInstallNonAdmin.ps1`. - -ChocolateyInstallNonAdmin.ps1: - -~~~powershell -# Set directory for installation - Chocolatey does not lock -# down the directory if not the default -$InstallDir='C:\ProgramData\chocoportable' -$env:ChocolateyInstall="$InstallDir" - -# If your PowerShell Execution policy is restrictive, you may -# not be able to get around that. Try setting your session to -# Bypass. -Set-ExecutionPolicy Bypass -Scope Process -Force; - -# All install options - offline, proxy, etc at -# https://chocolatey.org/install -iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) -~~~ - -Examples of packages you can install: - -~~~powershell -choco install puppet-agent.portable -y -choco install ruby.portable -y -choco install git.commandline -y - -# pick an editor -#choco install visualstudiocode.portable -y # not yet available -choco install notepadplusplus.commandline -y -#choco install nano -y -#choco install vim-tux.portable - -# What else can I install without admin rights? -# https://community.chocolatey.org/packages?q=id%3Aportable -~~~ - -If you prefer or need cmd.exe example, please see https://gist.github.com/ferventcoder/78fa6b6f4d6e2b12c89680cbc0daec78 - -
- -## Upgrading Chocolatey - -Once installed, Chocolatey can be upgraded in exactly the same way as any other package that has been installed using Chocolatey. Simply use the command to upgrade to the latest stable release of Chocolatey: - -~~~ -choco upgrade chocolatey -~~~ - -## Uninstalling Chocolatey - -See [uninstall](xref:choco-uninstallation). - -## FAQs - -### I'm having trouble installing Chocolatey - -Make sure you've reviewed More Install Options and looked over [Troubleshooting](xref:troubleshooting). If you've done those things, reach out over the mailing list or over [chat](https://ch0.co/community). The links to those can be found in the open source section of https://chocolatey.org/support. - -### I'm getting a 403 attempting to install - -This is addressed in [Troubleshooting](xref:troubleshooting). - -

 

diff --git a/input/en-us/choco/troubleshooting/dependency-troubles.md b/input/en-us/choco/troubleshooting/dependency-troubles.md deleted file mode 100644 index cd198dcddb..0000000000 --- a/input/en-us/choco/troubleshooting/dependency-troubles.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -Order: 10 -xref: choco-dependency-troubles -Title: Dependency Troubleshooting in Chocolatey CLI -Description: Troubleshooting steps for when you encounter issues related to dependencies ---- - -## Installation and Upgrade Commands Fail for Many Seemingly Unrelated Packages - -Due to the way dependency resolution works, packages with dependencies can occasionally trigger undesirable behavior. -When this happens, you will often be presented with both warnings and errors. -The most important information will be in the errors, and not the warnings. - -When you encounter these errors, it is recommended to start with the package name mentioned in the error, and attempt to install it. -Repeat this process with any other failing dependencies until they're all installed. - -### Example 1 - Upgrade All Fails to Upgrade One or More Packages - -This will sometimes be encountered with meta-packages, such as `obs-studio` which takes an exact-version dependency on `obs-studio.install`. -When running `choco upgrade all` it will attempt to upgrade every installed package. -Any packages which fail to install may be retried as part of a later dependency chain. -For example, `obs-studio.install` may be upgraded, fail, and then later be tried again as part of the dependency chain for `obs-studio` itself. -As a result, Chocolatey CLI's packages may be in an inconsistent state. -This is typically characterized by a dependency resolution error message when performing package operations: - -```cmd -Unable to resolve dependencies. 'obs-studio.install 29.0.2' is not compatible with 'obs-studio 29.1.1 constraint: obs-studio.install (>= 29.1.1)'. -``` - -This is normally resolved by upgrading the affected dependency. -In this example, you would run `choco upgrade obs-studio.install` to resolve the issue. - -The following scenario illustrates what can happen during an `upgrade all` where a dependency fails to install. -In this example, `obs-studio` installs, but `obs-studio.install` fails. -Due to the dependency version range specified by `obs-studio`, the version of `obs-studio.install` that remains installed (due to the upgrade failure) does not satisfy the dependency requirement. - -To resolve the issue, we run `choco upgrade obs-studio.install` to get the correct dependency version installed. -For packages that have a specific version dependency, add the `--version` option and specify the exact version to install. - -![Partial output from choco upgrade all, showing that obs-studio.install is attempted and failed](/assets/images/chocolatey/dependency-resolution-failure-1.png) - -![Continued output from choco upgrade all, showing that obs-studio metapackage is installed and subsequently re-attempts the upgrade to obs-studio.install which again fails, followed by a dependency resolution error in the next package and failing a seemingly unrelated package installation](/assets/images/chocolatey/dependency-resolution-failure-2.png) - -### Example 2 - Installing a Package Fails Due to Existing Missing Dependencies - -> :choco-warning: **WARNING** -> -> This example deals with multiple missing dependencies, and installs them while ignoring dependencies. -> You will need to ensure you're installing the correct versions required for your dependencies. - -The following scenario illustrates what can happen during an `install` where multiple existing packages have dependencies that are not currently met. -In this example, `glab` is attempting to be installed, but a number of `KB` packages are missing from the Chocolatey `lib` directory. - -1. We start by attempting to install `glab`, and note that that the following error occurs. - - ![Output from choco install glab where it fails to resolve dependency 'KB306858'](/assets/images/chocolatey/kb-dependency-failure-1.png) - -1. To resolve the issue, we first run `choco install KB3063858` to install the first identified package. -We note that this fails to install, so we make note of the package it couldn't find (`KB2919355`) and we run `choco install KB3063858 --ignore-dependencies` to ignore the dependency failure. - - ![Output from choco install KB306858 where it fails to resolve dependency 'KB2919355'](/assets/images/chocolatey/kb-dependency-failure-2.png) - -1. Now that we have `KB3063858` installed, we attempt to run `choco install KB2919355` to install the next identified package. -Again we make note of the next package (`KB2999226`) and install this package while ignoring dependencies: `choco install KB2919355 --ignore-dependencies`. - - ![Output from choco install KB2919355 where it fails to resolve dependency 'KB2999226'](/assets/images/chocolatey/kb-dependency-failure-3.png) - -1. Now with `KB2919355` installed we continue with `choco install KB2999226`. -Again we make note of the next package (`KB2919442`) and install this package while ignoring dependencies: `choco install KB2999226 --ignore-dependencies`. - - ![Output from choco install KB2999226 where it fails to resolve dependency 'KB2919442'](/assets/images/chocolatey/kb-dependency-failure-4.png) - -1. Now with `KB2999226` installed, we attempt to run `choco install KB2919442`. -We see that this one is actually already installed, so we attempt to install `glab` again. -When `glab` fails to install, we make note of the next package missing in our chain: `chocolatey-windowsupdate.extension`. - - ![Output from choco install KB2919442 where it is already installed. Following output is from choco install glab where it fails to resolve dependency 'chocolatey-windowsupdate.extension'](/assets/images/chocolatey/kb-dependency-failure-5.png) - -1. We install this in the same way as before (`choco install chocolatey-windowsupdate.extension`, then `choco install chocolatey-windowsupdate.extension --ignore-dependencies`). - - ![Output from choco install chocolatey-windowsupdate.extension where it fails to resolve dependency 'KB3033929'](/assets/images/chocolatey/kb-dependency-failure-6.png) - -1. We install the next package (`KB3033929`) and note that it did not have any dependency failures. - - ![Output from choco install KB3033929 where it installs with no dependency failures](/assets/images/chocolatey/kb-dependency-failure-7.png) - -1. So, we attempt our install of `glab` once more. -Thankfully, we are able to install it with no dependency errors. - - ![Output from choco install glab where it finally installs](/assets/images/chocolatey/kb-dependency-failure-8.png) diff --git a/input/en-us/choco/troubleshooting/index.md b/input/en-us/choco/troubleshooting/index.md deleted file mode 100644 index 5cfe3af0a8..0000000000 --- a/input/en-us/choco/troubleshooting/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 100 -xref: choco-troubleshooting -Title: Chocolatey CLI Troubleshooting -Description: Having issues running Chocolatey, check here for solutions ---- diff --git a/input/en-us/choco/troubleshooting/unable-to-load-service-index.md b/input/en-us/choco/troubleshooting/unable-to-load-service-index.md deleted file mode 100644 index a3c378cfe9..0000000000 --- a/input/en-us/choco/troubleshooting/unable-to-load-service-index.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -Order: 10 -xref: choco-unable-to-load-service-index -Title: Unable to Load Service Index Errors -Description: Information on solutions/workarounds for a problem that can have multiple underlying causes ---- - -On occasion, you may run into issues where Chocolatey CLI is unable to communicate with a package source. -There are a number of possible reasons for this, many of which will result in a warning that looks like this: - -> Unable to load the service index for source . - -This page contains the currently known information about these errors, as well as how to further diagnose the problem and find a solution. - -## Finding the Underlying Error(s) - -In Chocolatey CLI v2.0.0 and v2.1.0, the underlying errors are not fully enumerated in the Chocolatey logs. -To discover the underlying issue causing the error in these versions, you will need to use a tool that can inspect network traffic, like Fiddler. -Gary Park has a [short YouTube video](https://www.youtube.com/watch?v=z4CwJ-MF7ik) describing how to use Fiddler to inspect the network traffic using Fiddler Classic. - -As of Chocolatey CLI v2.2.0, the underlying errors will all be logged, but only a portion of the total stack of errors will be shown by default. -If more information is required, you will need to check the chocolatey.log file or re-run the command with the `--debug` option to see the additional errors. - -## Known Issues - -### SSL / TLS Errors - -Some server configurations require specific TLS versions and cipher suites to be available in order for clients to connect to them. -As a result, users lacking these TLS versions or cipher suites may have issues communicating with package sources on these servers. -One such example is the Chocolatey Community Repository, which requires TLS 1.2 as a minimum. - -Some examples of these kinds of error messages are: - -> The request was aborted: Could not create SSL/TLS secure channel. - -> HTTPS handshake to community.chocolatey.org (for #3) failed. System.Security.Authentication.AuthenticationException A call to SSPI failed, see inner exception. -> < The function requested is not supported -> -> Win32 (SChannel) Native Error Code: 0x80090302 - -In these cases, one of two issues is present: - -1. Your operating system is not using TLS 1.2 by default. - TLS issues are mostly seen in older Windows systems, primarily Windows 7/Windows Server 2008 R2, and earlier. -1. Your operating system has a missing cipher suite that is required by the server. - -In both cases, this can be most easily resolved using the `iiscrypto` tool to configure your operating system correctly. -This can be installed via Chocolatey CLI with: - -```code -choco install iiscrypto -``` - -However, if you are having issues connecting to the Chocolatey Community Repository, you can [download the IIS Crypto tool from their website](https://www.nartac.com/Products/IISCrypto/) directly. -Once installed, open the IIS Crypto tool and follow these instructions: - -1. On the **Schannel** tab (which is shown on starting the IIS Crypto tool by default) click the **Best Practices** button. -1. You will be prompted to click the Apply button, but follow the next steps before doing so. -1. Click on the **Cipher Suites** tab in the menu on the left to switch to it. -1. Click the **Best Practices** button again. -1. Click the **Apply** button. -1. Restart your computer. - -If this does not resolve the issue, continue reading below. - -### Certificate Errors - -In some cases, users who are communicating with the Chocolatey Community Repository through a proxy server or a network gateway proxy have experienced issues where Chocolatey CLI is unable to verify the SSL Certificate. - -A common error message in these circumstances looks like this: - -> The remote certificate is invalid according to the validation procedure. - -To confirm whether the issue is related to your proxy configuration, we recommend temporarily bypassing or disabling the proxy in order to verify whether you are otherwise able to communicate with the Chocolatey Community Repository. - -Specific resolutions for various products which proxy traffic are outside the scope of this article; we suggest you contact your network administrator to resolve these issues. diff --git a/input/en-us/choco/uninstallation.md b/input/en-us/choco/uninstallation.md deleted file mode 100644 index 35eb4906b0..0000000000 --- a/input/en-us/choco/uninstallation.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -Order: 30 -xref: choco-uninstallation -Title: How to uninstall -Description: Information on how to uninstall Chocolatey -RedirectFrom: docs/uninstallation ---- - -# Uninstalling Chocolatey - -Should you decide you don't like Chocolatey, you can uninstall it simply by removing the folder (and the environment variable(s) that it creates). Since it is not actually installed in Programs and Features, you don't have to worry that it cluttered up your registry (however that's a different story for the applications that you installed with Chocolatey or manually). - -## Folder -Most of Chocolatey is contained in `C:\ProgramData\chocolatey` or whatever `$env:ChocolateyInstall` evaluates to. You can simply delete that folder. - -> :choco-info: **NOTE** -> -> You might first back up the sub-folders `lib` and `bin` just in case you find undesirable results in removing Chocolatey. Bear in mind not every Chocolatey package is an installer package, there may be some non-installed applications contained in these subfolders that could potentially go missing. Having a backup will allow you to test that aspect out. - -## Environment Variables -There are some environment variables that need to be adjusted or removed. - -* ChocolateyInstall -* ChocolateyToolsLocation -* ChocolateyLastPathUpdate -* PATH (will need updated to remove) - -## Script -There are no warranties on this script whatsoever, but here is something you can try: - -> :choco-warning: **WARNING** -> -> This will remove Chocolatey and all packages, software, and configurations in the Chocolatey Installation folder from your machine. Everything will be GONE. This is very destructive. DO NOT RUN this script unless you completely understand what the intention of this script is and are good with it. If you mess something up, we cannot help you fix it. - -> :choco-warning: **WARNING** -> -> Seriously, this script may destroy your machine and require a rebuild. It may have varied results on different machines in the same environment. Think twice before running this. - -

Click the red button below to reveal the uninstall scripts.

- -
-
- -If you also intend to delete the Chocolatey directory, remove the `-WhatIf` switch from the `Remove-Item` call near the bottom: - -~~~powershell -$VerbosePreference = 'Continue' -if (-not $env:ChocolateyInstall) { - $message = @( - "The ChocolateyInstall environment variable was not found." - "Chocolatey is not detected as installed. Nothing to do." - ) -join "`n" - - Write-Warning $message - return -} - -if (-not (Test-Path $env:ChocolateyInstall)) { - $message = @( - "No Chocolatey installation detected at '$env:ChocolateyInstall'." - "Nothing to do." - ) -join "`n" - - Write-Warning $message - return -} - -<# - Using the .NET registry calls is necessary here in order to preserve environment variables embedded in PATH values; - Powershell's registry provider doesn't provide a method of preserving variable references, and we don't want to - accidentally overwrite them with absolute path values. Where the registry allows us to see "%SystemRoot%" in a PATH - entry, PowerShell's registry provider only sees "C:\Windows", for example. -#> -$userKey = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment',$true) -$userPath = $userKey.GetValue('PATH', [string]::Empty, 'DoNotExpandEnvironmentNames').ToString() - -$machineKey = [Microsoft.Win32.Registry]::LocalMachine.OpenSubKey('SYSTEM\ControlSet001\Control\Session Manager\Environment\',$true) -$machinePath = $machineKey.GetValue('PATH', [string]::Empty, 'DoNotExpandEnvironmentNames').ToString() - -$backupPATHs = @( - "User PATH: $userPath" - "Machine PATH: $machinePath" -) -$backupFile = "C:\PATH_backups_ChocolateyUninstall.txt" -$backupPATHs | Set-Content -Path $backupFile -Encoding UTF8 -Force - -$warningMessage = @" - This could cause issues after reboot where nothing is found if something goes wrong. - In that case, look at the backup file for the original PATH values in '$backupFile'. -"@ - -if ($userPath -like "*$env:ChocolateyInstall*") { - Write-Verbose "Chocolatey Install location found in User Path. Removing..." - Write-Warning $warningMessage - - $newUserPATH = @( - $userPath -split [System.IO.Path]::PathSeparator | - Where-Object { $_ -and $_ -ne "$env:ChocolateyInstall\bin" } - ) -join [System.IO.Path]::PathSeparator - - # NEVER use [Environment]::SetEnvironmentVariable() for PATH values; see https://github.com/dotnet/corefx/issues/36449 - # This issue exists in ALL released versions of .NET and .NET Core as of 12/19/2019 - $userKey.SetValue('PATH', $newUserPATH, 'ExpandString') -} - -if ($machinePath -like "*$env:ChocolateyInstall*") { - Write-Verbose "Chocolatey Install location found in Machine Path. Removing..." - Write-Warning $warningMessage - - $newMachinePATH = @( - $machinePath -split [System.IO.Path]::PathSeparator | - Where-Object { $_ -and $_ -ne "$env:ChocolateyInstall\bin" } - ) -join [System.IO.Path]::PathSeparator - - # NEVER use [Environment]::SetEnvironmentVariable() for PATH values; see https://github.com/dotnet/corefx/issues/36449 - # This issue exists in ALL released versions of .NET and .NET Core as of 12/19/2019 - $machineKey.SetValue('PATH', $newMachinePATH, 'ExpandString') -} - -# Adapt for any services running in subfolders of ChocolateyInstall -$agentService = Get-Service -Name chocolatey-agent -ErrorAction SilentlyContinue -if ($agentService -and $agentService.Status -eq 'Running') { - $agentService.Stop() -} -# TODO: add other services here - -Remove-Item -Path $env:ChocolateyInstall -Recurse -Force -WhatIf - -'ChocolateyInstall', 'ChocolateyLastPathUpdate' | ForEach-Object { - foreach ($scope in 'User', 'Machine') { - [Environment]::SetEnvironmentVariable($_, [string]::Empty, $scope) - } -} - -$machineKey.Close() -$userKey.Close() -~~~ - -Additionally, the below code will remove the environment variables pointing to the tools directory that was managed by Chocolatey. -If you want to remove the actual directory from disk, remove the `-WhatIf` switch from the `Remove-Item` call below as well. - -~~~powershell -if ($env:ChocolateyToolsLocation -and (Test-Path $env:ChocolateyToolsLocation)) { - Remove-Item -Path $env:ChocolateyToolsLocation -WhatIf -Recurse -Force -} - -foreach ($scope in 'User', 'Machine') { - [Environment]::SetEnvironmentVariable('ChocolateyToolsLocation', [string]::Empty, $scope) -} -~~~ -
-
\ No newline at end of file diff --git a/input/en-us/chocolatey-components-dependencies-and-support-lifecycle.md b/input/en-us/chocolatey-components-dependencies-and-support-lifecycle.md deleted file mode 100644 index b1429d3c67..0000000000 --- a/input/en-us/chocolatey-components-dependencies-and-support-lifecycle.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -Order: 75 -xref: chocolatey-components-dependencies-and-support-lifecycle -Title: Chocolatey Components Dependencies and Support Lifecycle -Description: Provides information about the Support Lifecycle for various Chocolatey Components, as well as the dependencies between them. ---- - -## Product Support Lifecycle - -All of the latest released stable versions of Chocolatey products (Chocolatey CLI, Chocolatey GUI, Chocolatey Central Management, etc.) are fully supported and will periodically receive new features, bug fixes, and security fixes as appropriate. -We recommend customers update to the latest versions to benefit from new features and fixes as they are released. - -### Pre-v1.0 Products - -For any products that have not yet reached v1.0, **only the latest version is supported**. -We will continue to add features, fix bugs, and address security concerns as normal while we work towards a v1.0 release. - -### Version 1.0+ Products - -Once a product reaches v1.0, we recommend customers move to that version as soon as possible. -We will not continue to support v0.x versions once a product reaches v1.0. - -### Version 2.0+ Products - -Once a product reaches the second major release, the following will apply: - -1. We will support the previous major version with **security fixes** for Chocolatey For Business customers. - - For example: at v2.0, the latest v1.x version of the product will receive security fixes; at v3.0, only the latest v2.x version of the product will continue to receive security fixes. -1. We will support the previous major version with certain bug fixes (excepting bug fixes that require breaking changes) for Chocolatey For Business customers for six months following the release of the next major version. -1. No new features will be backported to the previous major version. - -## Supported Windows Versions - -Chocolatey products' support for Windows Operating Systems follows Microsoft's Support Lifecycle: if the Windows version is supported by Microsoft, Chocolatey products are supported on that version of Windows. - -> :choco-info: **NOTE** -> -> This information is up-to-date as of 17 April 2024. - -| Windows Server Operating System | End Of Support | -|------------------------------------------------------------------------------------------------------------------------------|-------------------| -| [Windows Server 2022](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2022) | 14 October 2031 | -| [Windows Server 2019](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2019) | 9 January 2029 | -| [Windows Server 2016](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2016) | 12 January 2027 | -| [Windows Server 2012 R2](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2012-r2) | 13 October 2026 | -| [Windows Server 2012](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2012) | 13 October 2026 | -| **Windows Client Operating System** | **End Of Support**| -| **Home and Pro Editions** | | -| [Windows 11 23H2](https://learn.microsoft.com/en-us/lifecycle/products/windows-11-home-and-pro) | 11 November 2025 | -| [Windows 11 22H2](https://learn.microsoft.com/en-us/lifecycle/products/windows-11-home-and-pro) | 8 October 2024 | -| [Windows 10 22H2](https://learn.microsoft.com/en-us/lifecycle/products/windows-10-home-and-pro) | 14 October 2025 | -| **Enterprise and Education Editions** | | -| [Windows 11 23H2](https://learn.microsoft.com/en-us/lifecycle/products/windows-11-enterprise-and-education) | 10 November 2026 | -| [Windows 11 22H2](https://learn.microsoft.com/en-us/lifecycle/products/windows-11-enterprise-and-education) | 14 October 2025 | -| [Windows 11 21H2](https://learn.microsoft.com/en-us/lifecycle/products/windows-11-enterprise-and-education) | 8 October 2024 | -| [Windows 10 22H2](https://learn.microsoft.com/en-us/lifecycle/products/windows-10-enterprise-and-education) | 14 October 2025 | -| [Windows 10 21H2](https://learn.microsoft.com/en-us/lifecycle/products/windows-10-enterprise-and-education) | 11 June 2024 | -| **LTSC Enterprise Editions** | | -| [Windows 10 LTSC 2021](https://learn.microsoft.com/en-us/lifecycle/products/windows-10-enterprise-ltsc-2021) | 12 January 2027 | -| [Windows 10 LTSC 2019](https://learn.microsoft.com/en-us/lifecycle/products/windows-10-enterprise-ltsc-2019) | 9 January 2029 | - -## Supported PowerShell Versions - -Chocolatey products' support for PowerShell follows the lifecycle of the operating system where it was first introduced. - -> :choco-info: **NOTE** -> -> This information is up-to-date as of 17 April 2024. - -| PowerShell Version | End Of Support | First Introduced | -|-----------------------------|-------------------|---------------------------------------------------------------------------| -| Windows PowerShell 5.1 | TBD | Windows 10 Anniversary Update and Windows Server 2016, WMF 5.1. | -| Windows PowerShell 5.0 | TBD | WMF 5.0 | -| Windows PowerShell 4.0 | 13 October 2026 | Windows 8.1 and Windows Server 2012 R2, WMF 4.0 | -| Windows PowerShell 3.0 | 13 October 2026 | Windows 8 and Windows Server 2012, WMF 3.0. | - - - - \ No newline at end of file diff --git a/input/en-us/chocolatey-gui-licensed-extension/index.md b/input/en-us/chocolatey-gui-licensed-extension/index.md deleted file mode 100644 index e8055c006b..0000000000 --- a/input/en-us/chocolatey-gui-licensed-extension/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 120 -xref: chocolatey-gui-licensed-extension -Title: Chocolatey GUI Licensed Extension -Description: This is a Chocolatey GUI extension that enables the licensed features of Chocolatey GUI ---- \ No newline at end of file diff --git a/input/en-us/chocolatey-gui-licensed-extension/release-notes.md b/input/en-us/chocolatey-gui-licensed-extension/release-notes.md deleted file mode 100644 index 807565ea2e..0000000000 --- a/input/en-us/chocolatey-gui-licensed-extension/release-notes.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -Order: 10 -xref: chocolatey-gui-licensed-extension-release-notes -Title: Release Notes -Description: Release Notes for Chocolatey GUI Extension -OgImage: https://img.chocolatey.org/social-share/release-notes-chocolatey-gui-licensed-extension-og.png -TwitterImage: https://img.chocolatey.org/social-share/release-notes-chocolatey-gui-licensed-extension-twitter.png ---- - -# Chocolatey Release Notes - Chocolatey GUI Licensed Extension -## Summary -This covers the release notes for the Chocolatey GUI Licensed Extension (`chocolateygui.extension`) package, where the commercial editions of Chocolatey GUI get their enhanced functionality. -Please see [Install the Licensed Edition](xref:setup-chocolatey-gui-licensed) for information on how to get and install the package. - -> :choco-info: **NOTE** -> -> This package is available to Chocolatey for Business customers only. - -## Other Release Notes - -- Refer to [Open Source Release Notes](xref:floss-release-notes) as commercial editions build on top of open source. -- Chocolatey for Business (C4B) customers - also refer to [Chocolatey Agent Release Notes](xref:agent-release-notes) and [Chocolatey Central Management Release Notes](xref:ccm-release-notes). - - - - - - -## 2.0.0 (May 31, 2023) - -> :choco-warning: **WARNING** -> -> Refer to our [Upgrade Guide](xref:upgrading-to-chocolatey-v2-v6) for recommendations before upgrading from 1.x versions to 2.x. - -### Improvement - -- Update to use latest releases of Chocolatey products. - - -## 1.0.3 (May 10, 2023) - -### Bug Fix - -- Fix - Update version ranges in nuspec file to use maximum inclusive rather than maximum exclusive. - - -## 2.0.0-beta-20230426 (April 26, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey GUI Licensed Extension and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this beta version of Chocolatey GUI Licensed Extension we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this beta release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Improvement - -- Update to use latest beta releases of Chocolatey products. - - -## 2.0.0-beta-20230412 (April 12, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey GUI Licensed Extension and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this beta version of Chocolatey GUI Licensed Extension we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this beta release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Improvement - -- Update to use latest beta releases of Chocolatey Components. - - -## 2.0.0-beta-20230321 (March 21, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey GUI Licensed Extension and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this beta version of Chocolatey GUI Licensed Extension we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this beta release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Improvement - -- Update to use latest beta releases of Chocolatey Components. - - -## 1.0.2 (March 13, 2023) - -### Bug Fixes - -- Fix - Chocolatey GUI v1.1.2 crashes on launch with Chocolatey GUI Licensed Extension installed - see [licensed #338](https://github.com/chocolatey/chocolatey-licensed-issues/issues/338). - -## 2.0.0-alpha-20230221 (February 21, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey GUI Licensed Extension and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this alpha version of Chocolatey GUI Licensed Extension we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this alpha release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Breaking Change - -- Upgrade to target version 2.0.0 of Chocolatey.Lib and version 2.0.0 of Chocolatey GUI assemblies. - - -## 1.0.1 (October 12, 2022) - -### Improvements - -- Update package version range for Chocolatey Licensed Extension to support 5.0.0+. - -## 1.0.0 (March 21, 2022) - -> :choco-warning: **WARNING** -> -> The dependencies of the chocolateygui.extension package have changed in this release. It now requires Chocolatey GUI v1.0.0 and Chocolatey Licensed Extension v4.0.0. - -### Breaking Changes - -- Add Chocolatey Licensed Extension dependency to package to ensure all required dependencies are installed during upgrade. -- Updates Chocolatey CLI dependency for package to v1.0.0. - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.4.0 (February 10, 2022) - -> :choco-warning: **WARNING** -> -> The dependencies of the chocolateygui.extension package have changed in this release, and it now requires Chocolatey GUI v0.20.0. - -### Breaking Change - -- Change target .NET Framework version to be 4.8 - see [#841](https://github.com/chocolatey/ChocolateyGUI/issues/841). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.3.0 (September 6, 2021) - -> :choco-warning: **WARNING** -> -> The dependencies of the chocolateygui.extension package have changed in this release, and it now requires Chocolatey CLI v0.11.1 and Chocolatey GUI v0.19.0. - -### Features - -- Add feature to allow disabling of the This PC source - see [licensed #228](https://github.com/chocolatey/chocolatey-licensed-issues/issues/228). -- Add feature to allow disabling of "Update All" button -see [licensed #240](https://github.com/chocolatey/chocolatey-licensed-issues/issues/240). - -### Improvements - -- [Security] XML External Entity attack in log4net (CVE-2018-1285) see [licensed #254](https://github.com/chocolatey/chocolatey-licensed-issues/issues/254). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.2.1 (March 29, 2021) - -### Bug Fix - -- Fix - Incorrect configuration database being used by Chocolatey GUI Licensed Extension when running as non-administrator user - see [licensed #209](https://github.com/chocolatey/chocolatey-licensed-issues/issues/209). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.2.0 (March 9, 2021) - -### Breaking Change - -- Update the default value for "NonAdmin Access to Settings" feature to be false - see [#601](https://github.com/chocolatey/ChocolateyGUI/issues/601). - -### Features - -- Provide ability for Chocolatey GUI to respect the background service allowed commands configuration option. -- Add a feature to toggle on/off a read only view for installed packages - see [licensed #201](https://github.com/chocolatey/chocolatey-licensed-issues/issues/201). -- Add a feature to toggle on/off the option to not attempt to download icons for packages - see [licensed #199](https://github.com/chocolatey/chocolatey-licensed-issues/issues/199). -- Add a configuration option to specify a default for a particular source when application loads - see [licensed #198](https://github.com/chocolatey/chocolatey-licensed-issues/issues/198). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## 0.1.0 (January 22, 2021) - -Initial preview release - -### Features - -- Branding - Support for branding portions of the Chocolatey GUI assets from provided assets. -- Provide ability to restrict access to Chocolatey GUI settings to only machine administrators. -- Packaging - Extension is deployable in the same way as the Chocolatey Licensed Extension. -- Provide visual indication in Chocolatey GUI when the Chocolatey GUI Licensed Extension is being used. - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
diff --git a/input/en-us/chocolatey-gui-licensed-extension/setup/index.md b/input/en-us/chocolatey-gui-licensed-extension/setup/index.md deleted file mode 100644 index dfeb12e30e..0000000000 --- a/input/en-us/chocolatey-gui-licensed-extension/setup/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 20 -xref: setup-chocolatey-gui-licensed -Title: Setup -Description: Information on how to install and setup Chocolatey GUI Licensed Extension ---- \ No newline at end of file diff --git a/input/en-us/chocolatey-gui-licensed-extension/setup/installation.md b/input/en-us/chocolatey-gui-licensed-extension/setup/installation.md deleted file mode 100644 index daab685c3b..0000000000 --- a/input/en-us/chocolatey-gui-licensed-extension/setup/installation.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -Order: 10 -xref: chocolatey-gui-licensed-installation -Title: Installation -Description: Instructions on how to install Chocolatey GUI Licensed Extension ---- - -Once you have the [Chocolatey Licensed Extension](xref:setup-licensed) installed -the easiest way to install Chocolatey GUI Licensed Extension is to use Chocolatey. -Use the following command to install the latest version of Chocolatey GUI Licensed -Extension: - -```powershell -choco install chocolateygui.extension -``` - -## Upgrading Chocolatey GUI Licensed Extension - -If you already have Chocolatey GUI Licensed Extension installed, you can upgrade -to the latest version using the following command: - -```powershell -choco upgrade chocolateygui.extension -``` \ No newline at end of file diff --git a/input/en-us/chocolatey-gui-licensed-extension/setup/uninstallation.md b/input/en-us/chocolatey-gui-licensed-extension/setup/uninstallation.md deleted file mode 100644 index 77b999d2e1..0000000000 --- a/input/en-us/chocolatey-gui-licensed-extension/setup/uninstallation.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -Order: 20 -xref: chocolatey-gui-licensed-uninstallation -Title: Uninstallation -Description: Instructions on how to uninstall Chocolatey GUI Licensed Extension ---- - -Chocolatey GUI Licensed Extension can be easily uninstalled using the following command: - -```powershell -choco uninstall chocolateygui.extension -``` \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/business-features/admin-only-sources.md b/input/en-us/chocolatey-gui/business-features/admin-only-sources.md deleted file mode 100644 index 3e60ee6017..0000000000 --- a/input/en-us/chocolatey-gui/business-features/admin-only-sources.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -Order: 20 -xref: admin-only-sources -Title: Admin Only Sources -Description: Restrict access to sources based on Admin Only property ---- - -When Chocolatey GUI is used in conjunction with a Licensed version of Chocolatey, it is possible to restrict access to sources that have been configured on the system, using the Admin Only property. - -If this setting has been set to true on a source, Chocolatey GUI will no longer show it within the application when it is being used by a non-admin user. - -> :choco-info: **NOTE** -> -> This feature will only be supported in the Open Source version of Chocolatey GUI when using a licensed version of Chocolatey. Open Source Chocolatey will always report all sources that have been configured, regardless of whether they have been marked as Admin Only. - -## Resources - -Below is a short video which shows this feature in action: - -
- -
diff --git a/input/en-us/chocolatey-gui/business-features/branding.md b/input/en-us/chocolatey-gui/business-features/branding.md deleted file mode 100644 index c852873e93..0000000000 --- a/input/en-us/chocolatey-gui/business-features/branding.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -Order: 10 -xref: gui-branding -Title: Branding -Description: Information about applying branding to the Chocolatey GUI application ---- - -There is a Chocolatey for Business feature that allows applying branding to the Chocolatey GUI application. This allows customers to make Chocolatey GUI "look" more like their internal application. - -Visit the [branding page](xref:branding) for full details on how this can be achieved. diff --git a/input/en-us/chocolatey-gui/business-features/index.md b/input/en-us/chocolatey-gui/business-features/index.md deleted file mode 100644 index d2ba421b10..0000000000 --- a/input/en-us/chocolatey-gui/business-features/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 50 -xref: gui-business-features -Title: Business Features -Description: Information about additional features that can be added using Chocolatey GUI for Business ---- \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/commands/config.md b/input/en-us/chocolatey-gui/commands/config.md deleted file mode 100644 index 505258f2de..0000000000 --- a/input/en-us/chocolatey-gui/commands/config.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -Order: 10 -xref: gui-config-command -Title: Config -Description: Usage instructions on how to list/get/set/unset Chocolatey GUI config settings ---- - -Chocolatey GUI will allow you to interact with the config settings. - -## Usage - -```powershell -chocolateyguicli config [list]|get|set|unset [ -
- -
-
-

- -## Configuration Options - -The available items that can be configured are: - - diff --git a/input/en-us/chocolatey-gui/commands/feature.md b/input/en-us/chocolatey-gui/commands/feature.md deleted file mode 100644 index dd6460d262..0000000000 --- a/input/en-us/chocolatey-gui/commands/feature.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -Order: 20 -xref: gui-feature-command -Title: Feature -Description: Usage instructions on how to enable/disable Chocolatey GUI features ---- - -Chocolatey GUI will allow you to interact with features. - -## Usage - -```powershell -chocolateyguicli feature [list]|disable|enable [ -
- -
-
-

- -## Feature Options - -The available features that can be configured are: - - diff --git a/input/en-us/chocolatey-gui/commands/index.md b/input/en-us/chocolatey-gui/commands/index.md deleted file mode 100644 index 5c226f6e45..0000000000 --- a/input/en-us/chocolatey-gui/commands/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -Order: 40 -xref: gui-commands -Title: Commands -Description: Information about the various commands which can be used with Chocolatey GUI ---- - -While it is possible to configure all aspects of Chocolatey GUI from within the [Settings]() screen, it is also possible to configure all aspects directly from three commands which are exposed with the `chocolateyguicli` executable. This executable is installed with the Chocolatey GUI Chocolatey package, and is immediately available in both a PowerShell or Command window. Three commands, `config`, `feature`, and `purge` are available to control the different aspects of Chocolatey GUI. \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/commands/purge.md b/input/en-us/chocolatey-gui/commands/purge.md deleted file mode 100644 index 386ec903b5..0000000000 --- a/input/en-us/chocolatey-gui/commands/purge.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -Order: 30 -xref: gui-purge-command -Title: Purge -Description: Usage instructions on how to execute the purge command ---- - -Chocolatey GUI will allow you to interact with purging caches used in application. - -## Usage - -```powershell -chocolateyguicli purge icons|outdated [] -``` - -## Examples - -```powershell -chocolateyguicli purge icons -chocolateyguicli purge outdated -``` - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - -- 0: operation was successful, no issues detected -- -1 or 1: an error has occurred - -## Options and Switches - -```powershell --?, --help, -h - Prints out the help menu. - --r, --limitoutput, --limit-output - Limit the output to essential information -``` -## Resources - -Below is a short video which shows how to use the feature command of the chocolateyguicli: - -

-

- -
-
-

diff --git a/input/en-us/chocolatey-gui/index.md b/input/en-us/chocolatey-gui/index.md deleted file mode 100644 index a05942e8e6..0000000000 --- a/input/en-us/chocolatey-gui/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -Order: 100 -xref: chocolateygui -Title: Chocolatey GUI -Description: What is Chocolatey GUI -RedirectFrom: docs/chocolatey-gui-overview ---- - -## What is Chocolatey GUI? - -Chocolatey GUI is a WPF application that allows the installation, uninstallation, updating, and searching for Chocolatey Packages. It is intended as a replacement for the Chocolatey CLI for those that prefer interacting with an application, rather than with commands. - -## What functionality is offered by Chocolatey GUI? - -While Chocolatey GUI has a number of pieces of functionality, is doesn't have everything that is offered by the Chocolatey CLI. Over time, additional functionality will likely be added, but for the time being, the following is possible in Chocolatey GUI: - -- List Chocolatey Packages installed on local machine -- List Chocolatey Packages available for installation from remote sources -- Install/Uninstall/Update/Pin/Unpin Chocolatey Packages -- Add/Remove Chocolatey Sources -- Enable/disable Chocolatey Features -- Modify Chocolatey configuration values -- Visual indications provided when installed Chocolatey Packages are out of date -- List and Tile View of installed/available packages diff --git a/input/en-us/chocolatey-gui/known-issues.md b/input/en-us/chocolatey-gui/known-issues.md deleted file mode 100644 index 94163e0a85..0000000000 --- a/input/en-us/chocolatey-gui/known-issues.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -Order: 70 -xref: chocolateygui-known-issues -Title: Known Issues -Description: Current known issues regarding Chocolatey GUI -RedirectFrom: docs/chocolatey-gui-known-issues ---- - -## Not all available packages are shown, or there is no way to navigate to next page of results - -Chocolatey GUI is reliant on the repository server providing accurate information in order to determine whether there are more packages available than it was given in the first set of results. -In some implementations of NuGet v3 feeds, we have observed that the repository server is returning incorrect information. -As a result, there are cases where Chocolatey GUI may not be able to display all packages that the repository server has in its list. - -Currently, we are aware of this affecting Sonatype Nexus NuGet v3 repository feeds, but any repository implementation that reports incorrect metadata may result in similar issues. -Follow [the NEXUS-37861 Jira ticket](https://issues.sonatype.org/browse/NEXUS-38761) for further information on when this will be resolved by Sonatype. - -### Technical details - -Chocolatey GUI works on the concept of "pages" of packages. -This means that it will request only a subset of the total number of packages that exist on a particular repository server. -By default, Chocolatey GUI requests packages in a page size of 30. -If the page of packages returned has less than 30, Chocolatey GUI takes this to mean that there are no further packages to be returned, since it wasn't a full page. -In order for Chocolatey GUI to correctly display and paginate through all available packages, it is reliant on the correct information coming back from the repository server that is being queried. -In other words, the pages of packages that are returned need to be correct. - -During testing, there have been cases where a lower number of packages than was known to exist on the repository server was returned. -When this happens, Chocolatey GUI determines that there are no more packages on the server to request. -The result is that not all packages are displayed within Chocolatey GUI if this occurs. - -In addition, there have been cases where information about the total number of packages that exist on the repository server has not been returned correctly. -Where this has been witnessed to happen, the total number of packages is reported by the server as `1`, rather than the actual number. -Chocolatey GUI relies on this information in order to know how many pages of packages need to be shown, so that the correct `Next`, `Previous`, `First`, and `Last` buttons can be shown. -When the information is returned incorrectly from the repository server, the result is that all the pagination buttons are disabled, and can't be clicked. - -## Package installation arguments are not remembered when upgrading a package with Chocolatey GUI - -When the `useRememberedArgumentsForUpgrades` Chocolatey feature is enabled, package arguments are not correctly retained when upgrading packages. - -This is due to [a known bug in chocolatey.lib](https://github.com/chocolatey/choco/issues/2886). - -If you need to use this feature, you must currently upgrade affected packages via Chocolatey CLI instead of Chocolatey GUI. - - -## Chocolatey GUI asking for credentials for my non-administrator accounts - -If a user is a member of the Built-in AD group `Network Configuration Operators`, then that means they have an elevation token available and will be treated in the same way as administrative accounts. To fix this, you have two options: - -* Remove the users from `Network Configuration Operators` - PowerShell offers an alternative to `ipconfig /flushdns` that does not require admin permissions - `Clear-DnsClientCache`. -* OR change the ChocolateyGui.exe.manifest file in v0.17.0+ in the Chocolatey GUI folder under Program Files to `` (from `highestAvailable`). - -Please see the following [GitHub Issue](https://github.com/chocolatey/ChocolateyGUI/issues/629) for more details. - - -## Pin command does not work when running with Background Mode enabled - -In the current versions of Chocolatey CLI (v0.11.1) and Chocolatey GUI (v0.19.0), when attempting to pin a package using the Chocolatey CLI (choco.exe) with Background Mode enabled, things will work as expected. i.e. when running: `choco pin add --name="procmon"`. - -The procmon package will be correctly pinned. - -However, if you attempt the same operation via Chocolatey GUI, using the "Pin (Ignore Updates)" context menu, you will get an error stating: - -> Failed to pin package -> -> Exception: System.NullReferenceException: Object reference not set to an instance of an object - -This was fixed as part of a feature addition within [Chocolatey GUI Licensed Extension V 0.2.0](xref:chocolatey-gui-licensed-extension-release-notes#march-9-2021). - - -## chocolateyguicli Command Not Registered by System - -If you recieve an error in the shell stating `chocolateyguicli is not registered` or `ObjectNotFound`, please go through the following steps. - -1. Reinstall the `chococlateygui` package. `choco upgrade chocolateygui -y --force` -1. If step 1 did not fix the issue, please check that your antivirus software is not blocking the Chocolatey GUI Config from being written to. The Chocolatey GUI Config file can be located at `C:\ProgramData\Chocolatey GUI\Config\Data.db`. -1. If further assistance is needed please reach out via your support means. Listed by running `choco support`. If running Chocolatey OSS please reach out via our [Community Chat](https://ch0.co/community). - -## Package Installation Failures Don't Always Report Errors - -When installing packages with Chocolatey GUI, only the log output of the first installation is processed by Chocolatey GUI for reporting errors. - -This is due to a [known bug in Chocolatey GUI](https://github.com/chocolatey/ChocolateyGUI/issues/998). diff --git a/input/en-us/chocolatey-gui/localization.md b/input/en-us/chocolatey-gui/localization.md deleted file mode 100644 index af37d6c736..0000000000 --- a/input/en-us/chocolatey-gui/localization.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -Order: 60 -xref: gui-localization -Title: Localization -Description: Localization in Chocolatey GUI ---- - -## Basics - -To enable using localized strings in the Chocolatey GUI UI, the UI loads all its strings from a set of resource files called `resx` files. - -> :choco-info: **NOTE** -> -> Only the default `Resources.resx` file is committed into source control. All other translations are downloaded from transifex at the time of compilation (more information on this below). - -These `resx` files allows defining language and culture specific strings and resources, while having English fallbacks when they aren't present. -This allows Chocolatey GUI to, in general, be localization neutral. -For more information about localization using `resx` check the CultureInfo section on [MSDN](https://msdn.microsoft.com/en-us/library/system.globalization.cultureinfo(v=vs.110).aspx). - -The most important thing to remember is: each language has it's own `Resources..resx`, where `` is referring to the language culture name (as an example `de` for German or `nl` for Dutch). -A list of available cultures and their corresponding codes tags can be found [here](https://msdn.microsoft.com/en-us/library/cc233982.aspx). -If no fitting `` is present for the current system, the default/fallback `Resources.resx` - containing the English language will be chosen. - -When a new release of Chocolatey GUI is created, the resx files at the time of compilation are embedded within the generated assembly. -As a result, any modifications/additions to any files will not be available until the next release of Chocolatey GUI. - -> :choco-info: **NOTE** -> -> It is possible, assuming you have a transifex token, to download the resx files locally onto your environment. and compile Chocolatey GUI, will would allow you to test any changes locally. More information on this below. - -## transifex - -The Chocolatey GUI project makes use of the localization platform known as [transifex](https://www.transifex.com/). - -> :choco-info: **NOTE** -> -> This is normally a paid for service, however, we are using the Open Source offering that they provide. - -### Helping with translations - -In order to help with the localization effort for Chocolatey GUI, you will need to create an account on [transifex](https://www.transifex.com/). -Once you have an account, you will be able to request to join the [Chocolatey GUI](https://www.transifex.com/chocolatey/chocolatey-gui/dashboard/) project in transifex. - -> :choco-info: **NOTE** -> -> This request will need to be approved. - -If a request goes unapproved for a period of time, reach out on [Community Chat](https://ch0.co/community) for help. - -### Adding a new language - -If a language hasn't yet been created for the Chocolatey GUI project that you would like to help with, you will need to make a request to have it added. -This can be done via the [Chocolatey GUI dashboard](https://www.transifex.com/chocolatey/chocolatey-gui/dashboard/). - -> :choco-info: **NOTE** -> -> Adding a new language to the project will require approval. - -If a request goes unapproved for a period of time, reach out on [Community Chat](https://ch0.co/community) for help. - -> :choco-info: **NOTE** -> -> If you are requesting a new language that uses a full language code, for example `zh_CN` rather than a language code similar to `de`, please get in touch with one of the project maintainers, as a Pull Request similar to [this](https://github.com/chocolatey/ChocolateyGUI/pull/634) will be required. - -## Testing Other Languages - -### Download transifex files - -In order to test other languages within Chocolatey GUI, prior to a release, you will need to do the following: - -* Open an Administrative PowerShell Window -* Navigate to the folder where you have cloned the Chocolatey GUI repository -* Run the following command: - * `.\build.ps1 --target="Transifex-Pull-Translations"` -* You will be asked whether you have a transifex token - * If so, answer yes, and enter it - * If not, answer no, and you will be prompted for your transifex username/password -* Once all information is provided, hit enter -* All current resx files should be downloaded into the `Source\ChocolateyGui\Properties` folder -* Build the application by running the command: - * `.\build.ps1` -* Assuming that completes successfully, you should be able to install the generated MSI, which will contain the most recent translations available - -### Reset transifex authentication - -If for some reason you need to reset the authentication used by transifex, you will need to delete the persisted information. -This can be found in the root of your Users folder, in a file called `.transifexrc`. -Simply delete this file. -If you do this, you will need to run the `Transifex-Pull-Translations` task again, in order to provide the required information. - -### Temporary code change - -When testing another language (that does not match the current system locale), a little code-snippet has to be added. -Add the following to your App.xaml.cs (located at `Source/ChocolateyGui/App.xaml.cs`) (right before `application.Run();`) - -* **Don't forget** to remove this line of code after you're done testing! - -```cs -System.Threading.Thread.CurrentThread.CurrentUICulture = new System.Globalization.CultureInfo(""); -application.Run(); -``` - -> :choco-info: **NOTE** -> -> If you are unsure what you should replace `` with, a list of available cultures and their corresponding codes tags can be found [here](https://msdn.microsoft.com/en-us/library/cc233982.aspx). - -> :choco-info: **NOTE** -> -> There is an [open issue](https://github.com/chocolatey/ChocolateyGUI/issues/533) that would allow runtime modification of the current locale, but this hasn't been implemented yet. - -Once this has been implemented, this code change will no longer be required. - -## Adding New Strings To Chocolatey GUI - -The following rules of thumb apply for adding entirely new strings to Chocolatey GUI: - -* Always use static bindings (lang:Resources.xyz) -* Use context-sensitive names (`PageOrControlName_StringUsageHintOrName`) -* Always add the new String to `Resources.resx` (English) -* Only changes to this one file should be committed into source control -* Once your changes have been merged into the develop branch, the resx file will be uploaded to Transifex, which will then make the strings available for translation into other languages diff --git a/input/en-us/chocolatey-gui/release-notes.md b/input/en-us/chocolatey-gui/release-notes.md deleted file mode 100644 index fc8e00d862..0000000000 --- a/input/en-us/chocolatey-gui/release-notes.md +++ /dev/null @@ -1,657 +0,0 @@ ---- -Order: 10 -xref: chocolateygui-release-notes -Title: Release Notes -Description: Release Notes for Chocolatey GUI -OgImage: https://img.chocolatey.org/social-share/release-notes-chocolatey-gui-og.png -TwitterImage: https://img.chocolatey.org/social-share/release-notes-chocolatey-gui-twitter.png -RedirectFrom: docs/release-notes-chocolatey-gui ---- - -# Chocolatey GUI Release Notes - Open Source - -This covers changes for the "chocolateygui" package, which is available as FOSS. - -> :choco-info: **NOTE** -> -> For commercial editions, please also refer to [Licensed Release Notes](xref:licensed-extension-release-notes), as well at the [Chocolatey GUI Licensed Extension Release Notes](xref:chocolatey-gui-licensed-extension-release-notes). - - - - - -## 2.1.1 (April 29, 2024) - -> :choco-warning: **WARNING** -> -> Refer to our [Upgrade Guide](xref:upgrading-to-chocolatey-v2-v6) for recommendations before upgrading from 1.x versions to 2.x. - -### Bug Fixes - -- Fix - Chocolatey GUI not displaying error output when running as non-admin through Background Service - see [#967](https://github.com/chocolatey/ChocolateyGUI/issues/967). -- Fix - Chocolatey GUI does not start if the config folder is missing from `C:\ProgramData\Chocolatey GUI`. - see [#996](https://github.com/chocolatey/ChocolateyGUI/issues/996). - -## 2.1.0 (June 29, 2023) - -> :choco-warning: **WARNING** -> -> Refer to our [Upgrade Guide](xref:upgrading-to-chocolatey-v2-v6) for recommendations before upgrading from 1.x versions to 2.x. - -### Bug Fixes - -- Fix - Package version normalization is not being applied everywhere - see [#1005](https://github.com/chocolatey/ChocolateyGUI/issues/1005). -- Fix - Null reference exception is thrown when accessing the Chocolatey GUI settings screen - see [#1003](https://github.com/chocolatey/ChocolateyGUI/issues/1003). - -### Improvement - -- Provide ability to use option for Chocolatey CLI commands to skip cached HTTP query results - see [#1014](https://github.com/chocolatey/ChocolateyGUI/issues/1014). - - -## 2.1.0-alpha-20230608 (June 8, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey GUI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -### Bug Fixes - -- Fix - Package version normalization is not being applied everywhere - see [#1005](https://github.com/chocolatey/ChocolateyGUI/issues/1005). -- Fix - Null reference exception is thrown when accessing the Chocolatey GUI settings screen - see [#1003](https://github.com/chocolatey/ChocolateyGUI/issues/1003). - - -## 2.0.0 (May 31, 2023) - -> :choco-warning: **WARNING** -> -> Refer to our [Upgrade Guide](xref:upgrading-to-chocolatey-v2-v6) for recommendations before upgrading from 1.x versions to 2.0.0. - -### Breaking Changes - -- Upgrade to target version 3.1.0 of Chocolatey.NuGet.Client and version 2.0.0 of Chocolatey.Lib assemblies - see [#974](https://github.com/chocolatey/ChocolateyGUI/issues/974). -- Remove side-by-side installs - see [#989](https://github.com/chocolatey/ChocolateyGUI/issues/989). - -### Improvement - -- Ensure correct usage of ListCommand after upstream changes in Chocolatey CLI - see [#990](https://github.com/chocolatey/ChocolateyGUI/issues/990). - - -## 1.1.3 (May 10, 2023) - -### Bug Fix - -- Fix - Update version ranges in nuspec file to use maximum inclusive rather than maximum exclusive - see [#999](https://github.com/chocolatey/ChocolateyGUI/issues/999). - - -## 2.0.0-beta-20230426 (April 26, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey GUI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey GUI **only** works with the beta version of the Chocolatey GUI Licensed Extension. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this beta version of Chocolatey GUI we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this beta release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Improvements - -- Added handling for large package download counts, which causes an exception to be thrown when number is too large. -- Update to use latest beta releases of Chocolatey products. - - -## 2.0.0-beta-20230412 (April 12, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey GUI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey GUI **only** works with the beta version of the Chocolatey GUI Licensed Extension. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this beta version of Chocolatey GUI we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this beta release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Improvement - -- Update to use latest beta releases of Chocolatey Components. - - -## 2.0.0-beta-20230321 (March 21, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey GUI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey GUI **only** works with the beta version of the Chocolatey GUI Licensed Extension. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this beta version of Chocolatey GUI we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this beta release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Breaking Change - -- Remove side-by-side installs - see [#989](https://github.com/chocolatey/ChocolateyGUI/issues/989). - -## Enhancement - -- Ensure correct usage of ListCommand after upstream changes in Chocolatey CLI - see [#990](https://github.com/chocolatey/ChocolateyGUI/issues/990). - - -## 1.1.2 (March 8, 2023) - -### Improvements - -- Bump LiteDB dependency to 5.0.15 - see [#985](https://github.com/chocolatey/ChocolateyGUI/issues/985). - -## 2.0.0-alpha-20230307 (March 7, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey GUI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey GUI **only** works with the alpha version of the Chocolatey GUI Licensed Extension. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this alpha version of Chocolatey GUI we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this alpha release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Bug Fix - -- Fix - Chocolatey GUI MSI incorrectly included the `chocolatey.dll` and `chocolatey.pdb` files. - - -## 2.0.0-alpha-20230221 (February 21, 2023) - -> :choco-warning: **WARNING** -> -> This is a pre-release version of Chocolatey GUI and it is **NOT** suitable for production use! A pre-release version will have bugs that could have a detrimental impact to your environment. Ensure all necessary due diligence steps are taken before using in your environment. - -> :choco-warning: **WARNING** -> -> This pre-release version of Chocolatey GUI **only** works with the alpha version of the Chocolatey GUI Licensed Extension. - -> :choco-info: **NOTE** -> -> If you run into any problems when using this alpha version of Chocolatey GUI we would ask that you comment on this [discussion](https://github.com/chocolatey/choco/discussions/2995), which is where we will be collating issues, and providing workarounds, etc. We will not be accepting issues raised against this alpha release. - -### Known Issues - -See this [list](https://github.com/chocolatey/choco/discussions/2995) for known issues with this pre-release. - -### Breaking Change - -- Upgrade to target version 6.4.0 of NuGet.Client and version 2.0.0 of Chocolatey.Lib assemblies - see [#974](https://github.com/chocolatey/ChocolateyGUI/issues/974). - - -## [1.1.1](https://github.com/chocolatey/ChocolateyGUI/milestone/30?closed=1) (January 26, 2023) - -### Bug Fixes - -- Fix - Unable to load with Chocolatey GUI Licensed Extension - see [#977](https://github.com/chocolatey/ChocolateyGUI/issues/977). -- Fix - Cached file listing outdated packages is not updated when there are no changes - see [#978](https://github.com/chocolatey/ChocolateyGUI/issues/978). - -## [1.1.0](https://github.com/chocolatey/ChocolateyGUI/milestone/29?closed=1) (September 8, 2022) - -### Improvement - -- Add option to bypass confirmation dialogs of potentially destructive operations - see [#919](https://github.com/chocolatey/ChocolateyGUI/issues/919). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [1.0.0](https://github.com/chocolatey/ChocolateyGUI/milestone/28?closed=1) (March 21, 2022) - -> :choco-warning: **WARNING** -> -> The dependencies of the chocolateygui package have changed in this release. It now requires Chocolatey v1.0.0. - -### Breaking Change - -- Updates Chocolatey CLI dependency for package to v1.0.0 - see [#928](https://github.com/chocolatey/ChocolateyGUI/issues/928). - -### Bug Fix - -- Fix - Ensure keyboard shortcuts to navigate between sources works correctly when the show aggregated sources feature is enabled - see [#915](https://github.com/chocolatey/ChocolateyGUI/issues/915) - -### Documentation - -- Fix typo in window seen after export command finishes - see [#924](https://github.com/chocolatey/ChocolateyGUI/pull/924). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.20.0](https://github.com/chocolatey/ChocolateyGUI/milestone/23?closed=1) (February 10, 2022) - -> :choco-warning: **WARNING** -> -> If you install v0.20.0 of Chocolatey GUI then you will also have to install v0.4.0 of Chocolatey GUI Licensed Extension if you use it. You will see errors when attempting to run Chocolatey GUI if you do not do so. - -### Breaking Changes - -- Change target .NET Framework version to be 4.8 - see [#841](https://github.com/chocolatey/ChocolateyGUI/issues/841) - -### Features - -- Allow for passing in package parameters / installer arguments when installing a package - see [#545](https://github.com/chocolatey/ChocolateyGUI/issues/545). -- Allow users to change the locale to use - see [#533](https://github.com/chocolatey/ChocolateyGUI/issues/533). -- Provide ability to "see" persisted arguments for installed package - see [#770](https://github.com/chocolatey/ChocolateyGUI/issues/770). -- Provide ability to search/filter features and settings - see [#838](https://github.com/chocolatey/ChocolateyGUI/issues/838). -- Add confirmation dialog for update all button - see [#828](https://github.com/chocolatey/ChocolateyGUI/issues/828). -- Add confirmation dialog when removing a source - see [#827](https://github.com/chocolatey/ChocolateyGUI/issues/827). -- Add confirmation dialog when performing an Uninstall/Reinstall operation from context menu - see [#786](https://github.com/chocolatey/ChocolateyGUI/issues/786). - -### Bug Fixes - -- Fix - Install button is not disabled when installation of packages is not allowed - see [#911](https://github.com/chocolatey/ChocolateyGUI/issues/911). -- Fix - Message boxes used to report issues often don't stay open - see [#904](https://github.com/chocolatey/ChocolateyGUI/issues/904). -- Fix - All operations on packages with a progress dialog are broken - see [#875](https://github.com/chocolatey/ChocolateyGUI/issues/875). - -### Improvements - -- Ensure WiX installer verifies that .NET Framework 4.8 is installed - see [#842](https://github.com/chocolatey/ChocolateyGUI/issues/842). -- Order features and settings alphabetically - see [#837](https://github.com/chocolatey/ChocolateyGUI/issues/837). -- Support per-monitor DPI - see [#836](https://github.com/chocolatey/ChocolateyGUI/issues/836). -- Chocolatey GUI doesn't write to chocolatey.log - see [#697](https://github.com/chocolatey/ChocolateyGUI/issues/697). - -### Documentation - -- Gitter is still mentioned in the Readme - see [#898](https://github.com/chocolatey/ChocolateyGUI/issues/898). -- Fix link to localization article - see [#891](https://github.com/chocolatey/ChocolateyGUI/pull/891). -- Remove package parameters from nuspec file - see [#885](https://github.com/chocolatey/ChocolateyGUI/issues/885). -- Contributing.md has broken links - see [#854](https://github.com/chocolatey/ChocolateyGUI/issues/854). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.19.0](https://github.com/chocolatey/ChocolateyGUI/milestone/26?closed=1) (September 6, 2021) - -> :choco-warning: **WARNING** -> -> The dependencies of the chocolateygui package have changed in this release, and it now requires Chocolatey CLI v0.11.1. - -> :choco-warning: **WARNING** -> -> If you use Chocolatey GUI alongside the Chocolatey GUI Licensed Extension, if you install v0.19.0 of Chocolatey GUI then you will also have to install v0.3.0 of Chocolatey GUI Licensed Extension, or you will see errors when attempting to run Chocolatey GUI. - -### Improvements - -- [Security] XML External Entity attack in log4net (CVE-2018-1285) - see [#869](https://github.com/chocolatey/ChocolateyGUI/issues/869). -- Make use of Chocolatey CLI Export command - see [#882](https://github.com/chocolatey/ChocolateyGUI/issues/882). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.18.2](https://github.com/chocolatey/ChocolateyGUI/milestone/25?closed=1) (September 2, 2021) - -### Bug Fix - -- Fix - When running Chocolatey GUI, ensure installed Chocolatey assembly is used, rather than locally referenced assembly - see [#857](https://github.com/chocolatey/ChocolateyGUI/issues/857). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.18.1](https://github.com/chocolatey/ChocolateyGUI/milestone/24?closed=1) (March 29, 2021) - -### Bug Fixes - -- Fix - Chocolatey GUI fails to start in certain circumstances when running as a non-administrator user - [#829](https://github.com/chocolatey/ChocolateyGUI/issues/829). -- Fix - Ensure that transactions are persisted to configuration databases when making changes to Chocolatey GUI settings/features - see [#832](https://github.com/chocolatey/ChocolateyGUI/issues/832). -- Fix - Chocolatey GUI incorrectly reverts to list view after making a change in settings screen - see [#830](https://github.com/chocolatey/ChocolateyGUI/issues/830). - -### Documentation - -- Fix incorrect quoting of parameter in package nuspec - see [#831](https://github.com/chocolatey/ChocolateyGUI/issues/831). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.18.0](https://github.com/chocolatey/ChocolateyGUI/milestone/19?closed=1) (March 9, 2021) - -### Breaking Changes - -- Update the default value for tile view for local and remote source to be true - see [#820](https://github.com/chocolatey/ChocolateyGUI/issues/820). -- Update the default value for "NonAdmin Access to Settings" feature to be false - see [#601](https://github.com/chocolatey/ChocolateyGUI/issues/601). - -### Features - -- Add a feature to toggle on/off the option to not attempt to download icons for packages - see [#811](https://github.com/chocolatey/ChocolateyGUI/issues/811). -- Add a feature to toggle on/off a read only view for installed packages - see [#780](https://github.com/chocolatey/ChocolateyGUI/issues/780). -- Add a feature to toggle on/off the checking for outdated packages automatically - see [#769](https://github.com/chocolatey/ChocolateyGUI/issues/769). -- Add a feature to toggle on/off the preloading of packages when switching to remote views - see [#706](https://github.com/chocolatey/ChocolateyGUI/issues/706). -- Add a feature to toggle on/off dark mode for application UI - see [#685](https://github.com/chocolatey/ChocolateyGUI/issues/685). -- Add a configuration option to specify a default for a particular source when application loads - see [#808](https://github.com/chocolatey/ChocolateyGUI/issues/808). -- Provide ability to control which UI operations are allowed to be executed - see [#757](https://github.com/chocolatey/ChocolateyGUI/issues/757). -- Provide ability to set configuration at the machine level, rather than just at user level - see [#602](https://github.com/chocolatey/ChocolateyGUI/issues/602). -- Enable text search within local and remove views - when not using Tile View - see [#688](https://github.com/chocolatey/ChocolateyGUI/issues/688). - -### Bug Fixes - -- Fix - Option to only show packages with updates doesn't work correctly when automated outdated check is enabled - see [#821](https://github.com/chocolatey/ChocolateyGUI/issues/821). -- Fix - Configuration option to default to tile view for remote source is not respected - see [#782](https://github.com/chocolatey/ChocolateyGUI/issues/782). -- Fix - Using the UseDelayedSearch package parameter during installation doesn't work - see [#749](https://github.com/chocolatey/ChocolateyGUI/issues/749). -- Fix - Ensure that all features/config can be set via parameters during installation of package - see [#741](https://github.com/chocolatey/ChocolateyGUI/issues/741). - -### Improvements - -- Add keybinding for navigating between sources - see [#513](https://github.com/chocolatey/ChocolateyGUI/issues/513). -- Improve readability of settings description by wrapping text within cell - see [#813](https://github.com/chocolatey/ChocolateyGUI/issues/813). -- Improve how package icons with an svg extension are rendered - see [#756](https://github.com/chocolatey/ChocolateyGUI/issues/756). -- Improve how package icons with an ico extension are rendered - see [#739](https://github.com/chocolatey/ChocolateyGUI/issues/739). -- Improve order and spacing of context menu items to make it easier to use - see [#745](https://github.com/chocolatey/ChocolateyGUI/issues/745). -- Update wording of context menu items to make it clearer what they refer to - see [#730](https://github.com/chocolatey/ChocolateyGUI/issues/730). -- Update Svg.Skia and SkiaSharp dependencies - see [#812](https://github.com/chocolatey/ChocolateyGUI/pull/812). -- Update LiteDB to v5.0.5 - see [#763](https://github.com/chocolatey/ChocolateyGUI/pull/763). -- Update Automapper to v7.0.1 - see [#760](https://github.com/chocolatey/ChocolateyGUI/pull/760). - -### Documentation - -- Add link to wixtoolset Visual Studio integration - see [#792](https://github.com/chocolatey/ChocolateyGUI/pull/792). -- Update credits to include all 3rd party dependencies that are being used - see [#761](https://github.com/chocolatey/ChocolateyGUI/issues/761). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.17.3](https://github.com/chocolatey/ChocolateyGUI/milestone/22?closed=1) (February 1, 2021) - -### Bug Fix - -- Fix - Chocolatey GUI doesn't always shows the right list of software - see [#807](https://github.com/chocolatey/ChocolateyGUI/issues/807). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.17.2](https://github.com/chocolatey/ChocolateyGUI/milestone/21?closed=1) (July 13, 2020) - -### Bug Fixes - -- Fix - Ensure earlier versions of Chocolatey GUI assemblies can be resolved when using an older version of Chocolatey GUI extension - see [#785](https://github.com/chocolatey/ChocolateyGUI/issues/785). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.17.1](https://github.com/chocolatey/ChocolateyGUI/milestone/20?closed=1) (June 11, 2020) - -### Bug Fixes - -- Fix - Language localization files are missing in 0.17.0 - see [#778](https://github.com/chocolatey/ChocolateyGUI/issues/778). -- Fix - Chocolatey GUI runs as a 32 bit process when running on a 64 bit machine - see [#779](https://github.com/chocolatey/ChocolateyGUI/issues/779). - -### Release Video - -A short video explaining what is included in this release can be found here: - -
- -
- -## [0.17.0](https://github.com/chocolatey/ChocolateyGUI/milestone/18?closed=1) (March 26, 2020) - -### Features - -- Add ability to show/hide download count on remote source view - see [#710](https://github.com/chocolatey/ChocolateyGUI/issues/710). -- Create and publish additional NuGet packages for Chocolatey GUI - see [#698](https://github.com/chocolatey/ChocolateyGUI/issues/698). -- Provide integration with `chocolateygui.extension` - see [#679](https://github.com/chocolatey/ChocolateyGUI/issues/679). -- Create commands to allow purging of caches from CLI - see [#673](https://github.com/chocolatey/ChocolateyGUI/issues/673). -- Provide ability to purge Outdated Package cache file - see [#671](https://github.com/chocolatey/ChocolateyGUI/issues/671). -- Separate the app.manifest from the exe [Customer] - see [#629](https://github.com/chocolatey/ChocolateyGUI/issues/629). -- Provide ability to hide packages that are known to already be installed when viewing sources - see [#627](https://github.com/chocolatey/ChocolateyGUI/issues/627). -- Provide ability to refresh cached icons for packages when there are known changes to icon - see [#624](https://github.com/chocolatey/ChocolateyGUI/issues/624). -- Remove admin only sources/repos - see [#603](https://github.com/chocolatey/ChocolateyGUI/issues/603). -- Allow setting of Chocolatey GUI settings via Chocolatey package parameter - see [#592](https://github.com/chocolatey/ChocolateyGUI/issues/592). -- Search in all available repositories - see [#588](https://github.com/chocolatey/ChocolateyGUI/issues/588). -- Hide Download Counters - see [#569](https://github.com/chocolatey/ChocolateyGUI/issues/569). -- Limit non-admin list to self service only - see [#432](https://github.com/chocolatey/ChocolateyGUI/issues/432). - -### C4B Features - -- Add footer with information about current version in bottom left-hand corner - see [#705](https://github.com/chocolatey/ChocolateyGUI/issues/705). -- Add ability to strong name sign the output of the build - see [#704](https://github.com/chocolatey/ChocolateyGUI/issues/704). - -### Bug Fixes - -- Fix - PackageParameters are not working (when installing Chocolatey GUI via Chocolatey CLI) - see [#716](https://github.com/chocolatey/ChocolateyGUI/issues/716). -- Fix - Context menu not displayed - see [#709](https://github.com/chocolatey/ChocolateyGUI/issues/709). -- Fix - Correctly handle incorrect license installation - see [#686](https://github.com/chocolatey/ChocolateyGUI/issues/686). -- Fix - Packages with pre-release versioning never found on list/search - see [#676](https://github.com/chocolatey/ChocolateyGUI/issues/676). -- Fix - Empty icon doesn't appear on local source view - see [#674](https://github.com/chocolatey/ChocolateyGUI/issues/674). -- Fix - IsPrerelease property is never set - see [#661](https://github.com/chocolatey/ChocolateyGUI/issues/661). -- Fix - nuspec - Remove the upper bound dependency on Chocolatey CLI - see [#656](https://github.com/chocolatey/ChocolateyGUI/issues/656). -- Fix - Prerelease packages not being correctly labeled as "outdated" - see [#653](https://github.com/chocolatey/ChocolateyGUI/issues/653). -- Fix - Tile View - Nitpick inconsistent spacing - see [#652](https://github.com/chocolatey/ChocolateyGUI/issues/652). -- Fix - NotSupportedException:'System.NotSupportedException: UriTypeConverter cannot convert from (null) when viewing Package Details - see [#643](https://github.com/chocolatey/ChocolateyGUI/issues/643). -- Fix - nuspec - Add .NET Framework 4.x Dependency [Customer] - see [#632](https://github.com/chocolatey/ChocolateyGUI/issues/632). -- Fix - Unable to update source after making a change to another source [Customer] - see [#620](https://github.com/chocolatey/ChocolateyGUI/issues/620). -- Fix - Tile selection for Remote Sources is not being used - see [#618](https://github.com/chocolatey/ChocolateyGUI/issues/618). -- Fix - Unable to install a package that uses 64bit PowerShell Modules - see [#610](https://github.com/chocolatey/ChocolateyGUI/issues/610). -- Fix - Locking of generated packages.config file when exporting package list - see [#593](https://github.com/chocolatey/ChocolateyGUI/issues/593). -- Fix - Next/Previous First/Last buttons remain disabled when using Simple.Server [Customer] - see [#590](https://github.com/chocolatey/ChocolateyGUI/issues/590). -- Fix - Chocolatey GUI icon is a blank image - see [#589](https://github.com/chocolatey/ChocolateyGUI/issues/589). -- Fix - GUI misses update that shows in CLI - see [#585](https://github.com/chocolatey/ChocolateyGUI/issues/585). -- Fix - Chocolatey GUI crashes when opening details page for Rufus package - see [#584](https://github.com/chocolatey/ChocolateyGUI/issues/584). -- Fix - Chocolatey GUI crashes when viewing Package Details - see [#578](https://github.com/chocolatey/ChocolateyGUI/issues/578). -- Fix - Package shows as installed in GUI when it did not actually install [Customer] - see [#573](https://github.com/chocolatey/ChocolateyGUI/issues/573). -- Fix - Chocolatey GUI crashes on startup if all sources are disabled. - see [#568](https://github.com/chocolatey/ChocolateyGUI/issues/568). -- Fix - Chocolatey GUI v0.16.0 uninstall errors (but uninstalls) - see [#563](https://github.com/chocolatey/ChocolateyGUI/issues/563). -- Fix - Links in Settings/About page that result in "Page Not Found" errors - see [#562](https://github.com/chocolatey/ChocolateyGUI/issues/562). -- Fix - Icon not showing up in gallery - see [#558](https://github.com/chocolatey/ChocolateyGUI/issues/558). -- Fix - Package source link for Chocolatey GUI 0.15.0 in nuspec is wrong - see [#550](https://github.com/chocolatey/ChocolateyGUI/issues/550). -- Fix - Context Menu Position issue in the package details. - see [#548](https://github.com/chocolatey/ChocolateyGUI/issues/548). -- Fix - On Load of any source, outdated is running (logging) every time - see [#525](https://github.com/chocolatey/ChocolateyGUI/issues/525). -- Fix - Issue where Latest Version is not showing - see [#506](https://github.com/chocolatey/ChocolateyGUI/issues/506). -- Fix - Disable "Show Only Packages with Updates" while information is still loaded - see [#502](https://github.com/chocolatey/ChocolateyGUI/issues/502). - -### Improvements - -- Prerelease label should not be red as this suggests an error, which isn't the case - see [#711](https://github.com/chocolatey/ChocolateyGUI/issues/711). -- Move Windows specific code into another Common library - see [#682](https://github.com/chocolatey/ChocolateyGUI/issues/682). -- Remove tilting chocolatey logo - see [#680](https://github.com/chocolatey/ChocolateyGUI/issues/680). -- Split CLI functionality into separate exe - see [#675](https://github.com/chocolatey/ChocolateyGUI/issues/675). -- Allow "safe" Chocolatey operations to happen in parallel - see [#672](https://github.com/chocolatey/ChocolateyGUI/issues/672). -- Update to Chocolatey.Lib 0.10.15 - see [#670](https://github.com/chocolatey/ChocolateyGUI/issues/670). -- Ensure all dialogs shown in Chocolatey GUI have localized text on buttons - see [#668](https://github.com/chocolatey/ChocolateyGUI/issues/668). -- Do not display password in source settings screen - see [#665](https://github.com/chocolatey/ChocolateyGUI/issues/665). -- Tile View - Prevent Version text overlap - see [#651](https://github.com/chocolatey/ChocolateyGUI/issues/651). -- Ensure that icons maintain their aspect ratio - see [#633](https://github.com/chocolatey/ChocolateyGUI/issues/633). -- Improve UI for Feature and Settings lists - see [#612](https://github.com/chocolatey/ChocolateyGUI/pull/612). -- Upgrade MahApps.Metro and MahApps.Metro.IconPacks - see [#608](https://github.com/chocolatey/ChocolateyGUI/pull/608). -- Remove multiple uses of SetCustomLogging - see [#607](https://github.com/chocolatey/ChocolateyGUI/issues/607). -- Don't allow navigation to settings or about screen while dialog is open - see [#606](https://github.com/chocolatey/ChocolateyGUI/issues/606). -- Improve the descriptions/explanations used for Chocolatey GUI settings - see [#605](https://github.com/chocolatey/ChocolateyGUI/issues/605). -- Provide separate settings and about views - see [#598](https://github.com/chocolatey/ChocolateyGUI/issues/598). -- Chocolatey GUI not found in the PATH - see [#574](https://github.com/chocolatey/ChocolateyGUI/issues/574). -- Chocolatey GUI pulls download stats only from the community feed - see [#564](https://github.com/chocolatey/ChocolateyGUI/issues/564). -- Move version on Package view to the left column - see [#530](https://github.com/chocolatey/ChocolateyGUI/issues/530). -- Improve UI by reducing flashing when modal appears - see [#528](https://github.com/chocolatey/ChocolateyGUI/issues/528). -- Package description should use all available client space - see [#501](https://github.com/chocolatey/ChocolateyGUI/issues/501). -- Add different background for outdated packages - see [#431](https://github.com/chocolatey/ChocolateyGUI/issues/431). -- Package details view is missing the 'Gallery' link - see [#430](https://github.com/chocolatey/ChocolateyGUI/issues/430). -- Current prerelease does not display any versioning information in the ABOUT screen - see [#422](https://github.com/chocolatey/ChocolateyGUI/issues/422). -- Fix rendering of headings in package description - see [#356](https://github.com/chocolatey/ChocolateyGUI/issues/356). -- Add option to show package id column - see [#270](https://github.com/chocolatey/ChocolateyGUI/issues/270). - -### Documentation - -- Add Czech language map - see [#729](https://github.com/chocolatey/ChocolateyGUI/pull/729). -- Fix typo in readme - see [#693](https://github.com/chocolatey/ChocolateyGUI/issues/693). -- Added Chinese language map - see [#634](https://github.com/chocolatey/ChocolateyGUI/pull/634). -- Fix typo in about page - see [#583](https://github.com/chocolatey/ChocolateyGUI/pull/583). - -## [0.16.0](https://github.com/chocolatey/ChocolateyGUI/milestone/17?closed=1) (February 15, 2018) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.16.0). - -## [0.15.0](https://github.com/chocolatey/ChocolateyGUI/milestone/6?closed=1) (October 18, 2017) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.15.0). - -## [0.13.2](https://github.com/chocolatey/ChocolateyGUI/milestone/14?closed=1) (December 14, 2015) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.13.2). - -## [0.13.1](https://github.com/chocolatey/ChocolateyGUI/milestone/13?closed=1) (March 29, 2015) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.13.1). - -## [0.13.0](https://github.com/chocolatey/ChocolateyGUI/milestone/3?closed=1) (March 26, 2015) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.13.0). - -## [0.12.4](https://github.com/chocolatey/ChocolateyGUI/milestone/10?closed=1) (March 12, 2015) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.12.4). - -## [0.12.3](https://github.com/chocolatey/ChocolateyGUI/milestone/9?closed=1) (March 3, 2015) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.12.3). - -## [0.12.2](https://github.com/chocolatey/ChocolateyGUI/milestone/8?closed=1) (March 3, 2015) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.12.2). - -## [0.12.1](https://github.com/chocolatey/ChocolateyGUI/milestone/7?closed=1) (March 2, 2015) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.12.1). - -## [0.12.0](https://github.com/chocolatey/ChocolateyGUI/milestone/2?closed=1) (February 28, 2015) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.12.0). - -## [0.11.4](https://github.com/chocolatey/ChocolateyGUI/milestone/5?closed=1) (September 16, 2014) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.11.4). - -## 0.11.3 (September 16, 2014) - -No release notes available. - -## [0.11.2](https://github.com/chocolatey/ChocolateyGUI/milestone/4?closed=1) (September 16, 2014) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.11.2). - -## [0.11.1](https://github.com/chocolatey/ChocolateyGUI/milestone/11?closed=1) (February 24, 2013) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.11.1). - -## [0.11.0](https://github.com/chocolatey/ChocolateyGUI/milestone/1?closed=1) (February 24, 2013) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.11.0). - -## 0.1.4 (February 10, 2013) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.1.4). - -## 0.1.3 (February 10, 2013) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.1.3). - -## 0.1.2 (February 10, 2013) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.1.2). - -## 0.1.1 (February 10, 2013) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.1.1). - -## 0.1.0 (February 9, 2013) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.1.0). - -## 0.0.5 (September 10, 2011) - -Release notes can be found [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.0.5). - -## 0.0.4 (September 10, 2011) - -No release notes available. - -## 0.0.3 (September 10, 2011) - -No release notes available. - -## 0.0.2 (September 10, 2011) - -No release notes available. - -## 0.0.1 (September 10, 2011) - -No release notes available. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/allow-non-admin-access-to-settings.md b/input/en-us/chocolatey-gui/setup/configuration/features/allow-non-admin-access-to-settings.md deleted file mode 100644 index 49056a69f2..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/allow-non-admin-access-to-settings.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -Order: 100 -xref: allow-non-admin-access-to-settings -Title: Allow Non Admin Access to Settings -Description: Controls whether or not a non-administrator user can access the Settings Screen. NOTE - This feature will only work when using the licensed extension for Chocolatey and Chocolatey GUI. ---- - -When using Chocolatey GUI for Business a new feature is available in the Settings screen: - -![Allow non-admin access to Settings](/assets/images/chocolatey-gui/allow_non_admin_access_to_settings.png "Allow non-admin access to Settings") - -Which controls whether or not a non-admin user has access to the Settings screen or not. - -By default, this setting is enabled, so that we don't introduce a breaking change in the way that the application has worked to date. However, at some point, this will likely be flipped to not allowing non-admin users to access the settings. - -When this setting is turned off, a non-admin user will no longer be able to access the Settings screen, as shown below: - -![Access to Settings screen removed](/assets/images/chocolatey-gui/access_to_settings_removed.png "Access to Settings screen removed") - -> :choco-info: **NOTE** -> -> Regardless of this setting, an administrator user will always be able to access the Settings screen. - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'AllowNonAdminAccessToSettings'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'AllowNonAdminAccessToSettings'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'AllowNonAdminAccessToSettings'" --global - -chocolateyguicli feature disable --name="'AllowNonAdminAccessToSettings'" --global -``` - -## Default Value - -As of version 0.18.0 of Chocolatey GUI and Chocolatey GUI Licensed Extension, the default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.17.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.17.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/default-to-dark-mode.md b/input/en-us/chocolatey-gui/setup/configuration/features/default-to-dark-mode.md deleted file mode 100644 index 9e53c35689..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/default-to-dark-mode.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -Order: 150 -xref: default-to-dark-mode -Title: Default To Dark Mode -Description: Allows control over whether dark mode should be used by default or not ---- - -By default, Chocolatey GUI uses a light mode for all of its user interface. As a result, you will see a screen similar to the following when first starting the application: - -![Default to Dark Mode Disabled](/assets/images/chocolatey-gui/feature_default_to_dark_mode_disabled.png "Default to Dark Mode Disabled") - -It is possible to toggle between a light and dark mode for the application using the buttons at the top right hand corner of the application, but if you prefer to see the dark mode by default, then you can enable it with this feature. As a result, you will see something like the following when first starting the application: - -![Default to Dark Mode Enabled](/assets/images/chocolatey-gui/feature_default_to_dark_mode_enabled.png "Default to Dark Mode Enabled") - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'DefaultToDarkMode'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'DefaultToDarkMode'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'DefaultToDarkMode'" --global - -chocolateyguicli feature disable --name="'DefaultToDarkMode'" --global -``` - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.18.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.18.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/default-to-tile-view-for-local-source.md b/input/en-us/chocolatey-gui/setup/configuration/features/default-to-tile-view-for-local-source.md deleted file mode 100644 index 877d0ff148..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/default-to-tile-view-for-local-source.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -Order: 20 -xref: default-to-tile-view-for-local-source -Title: Default to Tile View for Local Source -Description: How to configure whether the tile or list view is used by default ---- - -By default (starting with version 0.18.0), Chocolatey GUI uses a tile view to show all of the packages that are currently installed locally on the -machine that is executing Chocolatey GUI. As a result, you will see a screen similar to the following when first -starting the application: - -![Default to Tile View for Local Source Disabled](/assets/images/chocolatey-gui/feature_default_tile_view_local_disabled.png "Default to Tile View for Local Source Disabled") - -It is possible to toggle between the list view and a tile view for the packages that are installed locally using the -buttons at the top right hand corner of the application, but it you prefer to see the list view by default, then you -can enable it with this feature. As a result, you will see something like the following when first starting the -application: - -![Default to Tile View for Local Source Enabled](/assets/images/chocolatey-gui/feature_default_tile_view_local_enabled.png "Default to Tile View for Local Source Enabled") - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'DefaultToTileViewForLocalSource'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'DefaultToTileViewForLocalSource'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'DefaultToTileViewForLocalSource'" --global - -chocolateyguicli feature disable --name="'DefaultToTileViewForLocalSource'" --global -``` - -## Default Value - -As of version 0.18.0 of Chocolatey GUI, the default value for this feature is enabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.16.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.17.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/default-to-tile-view-for-remote-source.md b/input/en-us/chocolatey-gui/setup/configuration/features/default-to-tile-view-for-remote-source.md deleted file mode 100644 index b431671945..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/default-to-tile-view-for-remote-source.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -Order: 30 -xref: default-to-tile-view-for-remote-source -Title: Default to Tile View for Remote Source -Description: How to configure whether the tile or list view is used by default ---- - -By default (starting with version 0.18.0), Chocolatey GUI uses a tile view to show all of the packages that are currently available on the remote -sources that have been configured. As a result, you will see a screen similar to the following when first -starting the application and clicking on a remote source: - -![Default to Tile View for Remote Source Disabled](/assets/images/chocolatey-gui/feature_default_tile_view_remote_disabled.png "Default to Tile View for Remote Source Disabled") - -It is possible to toggle between the list view and a tile view for the packages that are available on a remote source -using the buttons at the top right hand corner of the application, but it you prefer to see the list view by default, -then you can enable it with this feature. As a result, you will see something like the following when first starting -the application and clicking on a remote source: - -![Default to Tile View for Remote Source Enabled](/assets/images/chocolatey-gui/feature_default_tile_view_remote_enabled.png "Default to Tile View for Remote Source Enabled") - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'DefaultToTileViewForRemoteSource'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'DefaultToTileViewForRemoteSource'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'DefaultToTileViewForRemoteSource'" --global - -chocolateyguicli feature disable --name="'DefaultToTileViewForRemoteSource'" --global -``` - -## Default Value - -As of version 0.18.0 of Chocolatey GUI, the default value for this feature is enabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.16.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.17.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/exclude-installed-packages.md b/input/en-us/chocolatey-gui/setup/configuration/features/exclude-installed-packages.md deleted file mode 100644 index 97b65825dc..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/exclude-installed-packages.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -Order: 70 -xref: exclude-installed-packages -Title: Exclude Installed Packages -Description: Do not show packages that are already installed when viewing sources ---- - -By default, when viewing remote sources, such as the Chocolatey Community Repository, Chocolatey GUI will show you all -available packages, even if you already have them installed. Installed packages will be marked with a green banner, -indicating that they are currently installed. As a result, you may see something like the following: - -![Exclude Installed Packages Disabled](/assets/images/chocolatey-gui/feature_exclude_installed_packages_disabled.png "Exclude Installed Packages Disabled") - -By enabling this feature, packages that are already installed will no longer be shown in the list of available packages, -as shown here: - -![Exclude Installed Packages Enabled](/assets/images/chocolatey-gui/feature_exclude_installed_packages_enabled.png "Exclude Installed Packages Enabled") - -> :choco-info: **NOTE** -> -> When first enabling this feature, if the remote source was already open, it will be refresh to refresh the package list before the packages will be excluded. - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'ExcludeInstalledPackages'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'ExcludeInstalledPackages'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'ExcludeInstalledPackages'" --global - -chocolateyguicli feature disable --name="'ExcludeInstalledPackages'" --global -``` - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.17.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.17.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/hide-all-remote-chocolatey-sources.md b/input/en-us/chocolatey-gui/setup/configuration/features/hide-all-remote-chocolatey-sources.md deleted file mode 100644 index 717f564e68..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/hide-all-remote-chocolatey-sources.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -Order: 140 -xref: hide-all-remote-chocolatey-sources -Title: Hide All Remote Chocolatey Sources -Description: Allow control over whether Chocolatey GUI should be switched into a read-only mode of operation ---- - -There are times when you want to use Chocolatey GUI in a read-only mode, meaning that you can view what packages are currently installed, but to not allow access to install any other packages. When this is enabled, Chocolatey GUI would change from showing the following: - -![What Chocolatey GUI looks like before enabling the HideAllRemoteChocolateySources feature](/assets/images/chocolatey-gui/feature_hide_all_remote_chocolatey_sources_1.png "What Chocolatey GUI looks like before enabling the HideAllRemoteChocolateySources feature") - -to only showing a single "This PC" source: - -![What Chocolatey GUI looks like after enabling the HideAllRemoteChocolateySources feature](/assets/images/chocolatey-gui/feature_hide_all_remote_chocolatey_sources_2.png "What Chocolatey GUI looks like after enabling the HideAllRemoteChocolateySources feature") - -Notice that the `ChocolateyInternal` and `chocolatey.licensed` sources are no longer displayed. - - - - - - - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'HideAllRemoteChocolateySources'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'HideAllRemoteChocolateySources'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'HideAllRemoteChocolateySources'" --global - -chocolateyguicli feature disable --name="'HideAllRemoteChocolateySources'" --global -``` - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.18.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.18.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/hide-package-download-count.md b/input/en-us/chocolatey-gui/setup/configuration/features/hide-package-download-count.md deleted file mode 100644 index 7973962884..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/hide-package-download-count.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -Order: 120 -xref: hide-package-download-count -Title: Hide Package Download Count -Description: Allows control over whether package download count is displayed on remote source views ---- - -By default, Chocolatey GUI will attempt to show the download statistics for a package on a remote feed. This can be -useful when making a decision about whether to install a package or not. For example, when viewing the Chocolatey -Community Repository feed, you will see the following: - -![Hide Package Download Count Disabled 1](/assets/images/chocolatey-gui/feature_hide_package_download_count_disabled_1.png "Hide Package Download Count Disabled 1") - -However, when using a feed that doesn't support package download statistics, you can be shown the following which isn't -as useful: - -![Hide Package Download Count Disabled 2](/assets/images/chocolatey-gui/feature_hide_package_download_count_disabled_2.png "Hide Package Download Count Disabled 2") - -By enabling this feature, you can turn off package download count for all sources, and as a result, you will see the -following: - -![Hide Package Download Count Enabled 1](/assets/images/chocolatey-gui/feature_hide_package_download_count_enabled_1.png "Hide Package Download Count Enabled 1") - -![Hide Package Download Count Enabled 2](/assets/images/chocolatey-gui/feature_hide_package_download_count_enabled_2.png "Hide Package Download Count Enabled 2") - -> :choco-info: **NOTE** -> -> It is currently not possible to configure showing/hiding the package download count for individual feeds - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'HidePackageDownloadCount'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'HidePackageDownloadCount'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'HidePackageDownloadCount'" --global - -chocolateyguicli feature disable --name="'HidePackageDownloadCount'" --global -``` - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.17.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.17.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/hide-this-pc-source.md b/input/en-us/chocolatey-gui/setup/configuration/features/hide-this-pc-source.md deleted file mode 100644 index 5eecb683bc..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/hide-this-pc-source.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -Order: 160 -xref: hide-this-pc-source -Title: Hide This PC Source -Description: Allow control over whether Chocolatey GUI should show the local This PC source or not ---- - -There are times when you want to simplify the usage of Chocolatey GUI for your end users, and only show the sources where packages can be installed from, rather than including a source which lists all of the currently installed packages. When this feature is enabled, Chocolatey GUI would change from showing the following: - -![Hide This PC Source Disabled](/assets/images/chocolatey-gui/feature_hide_this_pc_source_disabled.png "Hide This PC Source Disabled") - -to only showing the available remote sources which are currently configured on the system: - -![Hide This PC Source Enabled](/assets/images/chocolatey-gui/feature_hide_this_pc_source_enabled.png "Hide This PC Source Enabled") - -Notice that the "This PC" source is no longer available. - - - - - - - -## Resources - -Below is a short video which shows this feature in action: - -> :choco-info: **NOTE** -> -> Coming soon - -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'HideThisPCSource'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'HideThisPCSource'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'HideThisPCSource'" --global - -chocolateyguicli feature disable --name="'HideThisPCSource'" --global -``` - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.19.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI v0.19.0. \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/index.md b/input/en-us/chocolatey-gui/setup/configuration/features/index.md deleted file mode 100644 index 49fec61e54..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 10 -xref: gui-features -Title: Features -Description: The available feature options for Chocolatey GUI ---- \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/prevent-all-package-icon-downloads.md b/input/en-us/chocolatey-gui/setup/configuration/features/prevent-all-package-icon-downloads.md deleted file mode 100644 index 05301d57a0..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/prevent-all-package-icon-downloads.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -Order: 130 -xref: prevent-all-package-icon-downloads -Title: Prevent All Package Icon Downloads -Description: Allows control over whether an attempt is made to download icons associated with packages ---- - -By default, when using the [DefaultToTileViewForLocalSource](xref:default-to-tile-view-for-local-source), [DefaultToTileViewForRemoteSource](xref:default-to-tile-view-for-remote-source), or the [ShowAdditionalPackageInformation](xref:show-additional-package-information) features, Chocolatey GUI will attempt to download the icon for the package from the URL that is defined within the nuspec file for the package. For the most part, this works without any problems, however, when being used within an air gapped network, with no internet access, the end result looks like this: - -![Showing what happens when Chocolatey GUI runs with no external internet access](/assets/images/chocolatey-gui/feature_prevent_all_package_icon_downloads_1.png "Showing what happens when Chocolatey GUI runs with no external internet access") - -With the PreventAllPackageIconDownloads feature enabled, no attempt will be made to download the icon associated with the package, and instead the default Chocolatey icon will be used for each package. The result being the following: - -![Showing what happens when Chocolatey GUI runs with no external internet access with PreventAllPackageIconDownloads enabled](/assets/images/chocolatey-gui/feature_prevent_all_package_icon_downloads_2.png "Showing what happens when Chocolatey GUI runs with no external internet access with PreventAllPackageIconDownloads enabled") - - - -> :choco-info: **NOTE** -> -> If Chocolatey GUI has been run before enabling this feature, make sure to [purge any existing icons](xref:gui-purge-icons) that may have been cached - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'PreventAllPackageIconDownloads'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'PreventAllPackageIconDownloads'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'PreventAllPackageIconDownloads'" --global - -chocolateyguicli feature disable --name="'PreventAllPackageIconDownloads'" --global -``` - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.18.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.18.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/prevent-automated-outdated-packages-check.md b/input/en-us/chocolatey-gui/setup/configuration/features/prevent-automated-outdated-packages-check.md deleted file mode 100644 index 096091a290..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/prevent-automated-outdated-packages-check.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -Order: 60 -xref: prevent-automated-outdated-packages-check -Title: Prevent Automated Outdated Packages Check -Description: Allows control over whether Chocolatey GUI will automatically check for outdated packages installed locally ---- - -By default, when the Chocolatey GUI application starts up it will immediately check to see what packages are outdated, so that this information can be displayed within the application. When this check is happening, you will see the following progress bar being shown: - -![Showing the outdated packages check in action](/assets/images/chocolatey-gui/feature_prevent_automated_outdated_packages_check_1.png "Showing the outdated packages check in action") - -Depending on the number of packages that you currently have installed, and the number of sources that you have configured, this check can take a long time. If you are not interested in having this check happen automatically, you can enable the PreventAutomatedOutdatedPackagesCheck feature. - -Once enabled, if you want to manually check the outdated status of packages that you have installed, you can still trigger this check using this button: - -![Showing where the manual check for outdated packages is located](/assets/images/chocolatey-gui/feature_prevent_automated_outdated_packages_check_2.png "Showing where the manual check for outdated packages is located") - -In addition, Chocolatey GUI does cache the information about which packages are outdated. The length of time that this information is cached can be controlled via the [OutdatedPackagesCacheDurationInMinutes](xref:outdated-packages-cache-duration-in-minutes) option. - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'PreventAutomatedOutdatedPackagesCheck'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'PreventAutomatedOutdatedPackagesCheck'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'PreventAutomatedOutdatedPackagesCheck'" --global - -chocolateyguicli feature disable --name="'PreventAutomatedOutdatedPackagesCheck'" --global -``` - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.18.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.18.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/prevent-preload.md b/input/en-us/chocolatey-gui/setup/configuration/features/prevent-preload.md deleted file mode 100644 index f05b9580bf..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/prevent-preload.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -Order: 50 -xref: prevent-preload -Title: Prevent Preload -Description: Allows control over whether packages are immediately fetched when navigating to a remote source view ---- - -By default, when navigating to a remote source (for example the Chocolatey Community Repository), Chocolatey GUI will fetch and display the first page of packages that can be installed. Depending on your use of Chocolatey GUI, you may want to immediately search for packages, rather than install from the first page of packages. If you enable the Prevent Preload feature, than the first pages of packages will not be fetched, and instead, you will be able to immediately search for a package that you want to install. - -When enabled, you will see the following when navigating to a remote source: - -![Prevent Preload is enabled, showing the ability to immediately search for packages](/assets/images/chocolatey-gui/feature_prevent_preload.png "Prevent Preload is enabled, showing the ability to immediately search for packages") - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'PreventPreload'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'PreventPreload'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'PreventPreload'" --global - -chocolateyguicli feature disable --name="'PreventPreload'" --global -``` - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.18.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.18.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/prevent-usage-of-update-all-button.md b/input/en-us/chocolatey-gui/setup/configuration/features/prevent-usage-of-update-all-button.md deleted file mode 100644 index f2a70e2176..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/prevent-usage-of-update-all-button.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -Order: 170 -xref: prevent-usage-of-update-all-button -Title: Prevent usage of Update All button -Description: Allows control over whether the Update All button should be available or not ---- - -Chocolatey GUI has always had the ability to run the equivalent of the `choco upgrade all` command, via the [Update All button](xref:gui-update-all). However, there are times when you want to provide finer grain control of what packages are being updated at any given time. As such, this feature allowing removal of the Update All button from the Chocolatey GUI user interface. - -By default, the Update All button will be shown: - -![Show the update all button in the Chocolatey GUI UI](/assets/images/chocolatey-gui/user_interface_main-window_action_update-all_2.png "Show the update all button in the Chocolatey GUI UI") - -however, once this feature is enabled, it will no longer be shown - -![Show the update all button removed in the Chocolatey GUI UI](/assets/images/chocolatey-gui/user_interface_main-window_update-all-removed.png "Show the update all button removed in the Chocolatey GUI UI") - - - - - -## Resources - -Below is a short video which shows this feature in action: - -> :choco-info: **NOTE** -> -> Coming soon - -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'PreventUsageOfUpdateAllButton'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'PreventUsageOfUpdateAllButton'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'PreventUsageOfUpdateAllButton'" --global - -chocolateyguicli feature disable --name="'PreventUsageOfUpdateAllButton'" --global -``` - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.19.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI v0.19.0. \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/show-additional-package-information.md b/input/en-us/chocolatey-gui/setup/configuration/features/show-additional-package-information.md deleted file mode 100644 index 8094489deb..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/show-additional-package-information.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -Order: 90 -xref: show-additional-package-information -Title: Show Additional Package Information -Description: Show additional package information on Local and Remote views ---- - -By default, when using the list view for local and remote sources, a limited set of information is provided. This -information is the minimum amount of information that is required to make informed decisions about interacting with the -packages that are shown. As a result, when using Chocolatey GUI, you will see the following when using the local -source: - -![Show Additional Package Information Disabled 1](/assets/images/chocolatey-gui/feature_show_additional_package_information_disabled_1.png "Show Additional Package Information Disabled 1") - -And the following when using a remote source: - -![Show Additional Package Information Disabled 2](/assets/images/chocolatey-gui/feature_show_additional_package_information_disabled_2.png "Show Additional Package Information Disabled 2") - -By enabling this feature, you allow the addition of extra package information to be displayed. For example, in the -local source view, you will see additional columns for package id and whether or not it is a pre-release package: - -![Show Additional Package Information Enabled 1](/assets/images/chocolatey-gui/feature_show_additional_package_information_enabled_1.png "Show Additional Package Information Enabled 1") - -And in the remote source view, it will be rendered as follows: - -![Show Additional Package Information Enabled 2](/assets/images/chocolatey-gui/feature_show_additional_package_information_enabled_2.png "Show Additional Package Information Enabled 2") - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'ShowAdditionalPackageInformation'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'ShowAdditionalPackageInformation'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'ShowAdditionalPackageInformation'" --global - -chocolateyguicli feature disable --name="'ShowAdditionalPackageInformation'" --global -``` - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.17.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.17.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/show-aggregated-source-view.md b/input/en-us/chocolatey-gui/setup/configuration/features/show-aggregated-source-view.md deleted file mode 100644 index 5152c3a2bd..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/show-aggregated-source-view.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -Order: 80 -xref: show-aggregated-source-view -Title: Show Aggregated Source -Description: Show additional source combining all sources in one place ---- - -By default, Chocolatey GUI shows a source view for every feed that is configured for Chocolatey. Clicking on each tab -will show all of the packages for that selected feed. As a result, the normal Chocolatey GUI view looks something like -the following: - -![Show Aggregated Source Disabled](/assets/images/chocolatey-gui/feature_show_aggregated_source_disabled.png "Show Aggregated Source Disabled") - -By enabling this feature, it is possible to add an additional source view, which aggregates all the packages from all -configured sources, into a single view. Once enabled, you will see a new `All Sources` tab available for selection, -similar to the following: - -![Show Aggregated Source Enabled](/assets/images/chocolatey-gui/feature_show_aggregated_source_enabled.png "Show Aggregated Source Enabled") - -> :choco-info: **NOTE** -> ->When first enabling this feature, it will be necessary to close and re-open Chocolatey GUI in order to see the new source view. - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'ShowAggregatedSourceView'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'ShowAggregatedSourceView'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'ShowAggregatedSourceView'" --global - -chocolateyguicli feature disable --name="'ShowAggregatedSourceView'" --global -``` - - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.17.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.17.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/show-console-output.md b/input/en-us/chocolatey-gui/setup/configuration/features/show-console-output.md deleted file mode 100644 index 89d7613a36..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/show-console-output.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -Order: 10 -xref: show-console-output -Title: Show Console Output -Description: Shows output from the commands being executed when a job is running ---- - -By default, when Chocolatey GUI begins what is known to be an operation that can take a while, it will show a loading -modal window. When this modal is shown, there is the option to also show the console output for the operation that is -currently being executed. - -This is what you will see when an operation like this happens, and this feature is disabled: - -![Show Console Output Disabled](/assets/images/chocolatey-gui/feature_show_console_output_disabled.png "Show Console Output Disabled") - -When this feature becomes enabled, you will be default be able to see the contents of the console output, without having -to first expand it: - -![Show Console Output Enabled](/assets/images/chocolatey-gui/feature_show_console_output_enabled.png "Show Console Output Enabled") - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'ShowConsoleOutput'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'ShowConsoleOutput'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'ShowConsoleOutput'" --global - -chocolateyguicli feature disable --name="'ShowConsoleOutput'" --global -``` - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.15.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.17.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/use-delayed-search.md b/input/en-us/chocolatey-gui/setup/configuration/features/use-delayed-search.md deleted file mode 100644 index e61a48c26e..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/use-delayed-search.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -Order: 40 -xref: use-delayed-search -Title: Use Delayed Search -Description: Enables live search, which returns results after a short delay without clicking the search button on remote sources ---- - -By default, when viewing any remote source in Chocolatey GUI (for example, the Chocolatey Community Repository), in order to start a search it is necessary to press the enter button (or to click the magnifying glass icon) after entering the search string. Some people prefer that the search is executed immediately after typing has completed, without the need to press the enter button. Enabling this feature toggles it so that pressing the entry key is no longer a requirement for the search to be performed. - -![Use Delayed Search Enabled](/assets/images/chocolatey-gui/feature_use_delayed_search_enabled.png "Use Delayed Search Enabled") - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'UseDelayedSearch'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'UseDelayedSearch'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'UseDelayedSearch'" --global - -chocolateyguicli feature disable --name="'UseDelayedSearch'" --global -``` - - -## Default Value - -The default value for this feature is disabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.16.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.17.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/features/use-keyboard-bindings.md b/input/en-us/chocolatey-gui/setup/configuration/features/use-keyboard-bindings.md deleted file mode 100644 index 851776f8f4..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/features/use-keyboard-bindings.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -Order: 110 -xref: use-keyboard-bindings -Title: Use Keyboard Bindings -Description: Allows keyboard bindings to be used to interact with different areas of the Chocolatey GUI User Interface ---- - -By default, Chocolatey GUI ships with some keyboard bindings that make navigating sources easier when using the -keyboard. In the screenshot below, it is possible to navigate to the `chocolatey.licensed` feed using `CTRL + 3` and -then back to the `This PC` feed using `CTRL + 1`. It is also possible to navigate to the `chocolatey` feed using -`CTRL + 2`. - -![Use Keyboard Bindings](/assets/images/chocolatey-gui/feature_use_keyboard_bindings.png "Use Keyboard Bindings") - -Disabling this feature will stop these navigations from being possible using these keyboard shortcuts, but they can -still be navigated to using the mouse in the normal way. - -> :choco-info: **NOTE** -> ->Keyboard bindings are only supported for the first 9 sources. Trying to press `CTRL + 1 + 0` for navigating to a tenth source will not work. - -## Resources - -Below is a short video which shows this feature in action: - -

-

- -
-
-

- -## Example - -This feature can be enabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature enable --name="'UseKeyboardBindings'" -``` - -This feature can be disabled, for the currently logged in user, by running the following command: - -```powershell -chocolateyguicli feature disable --name="'UseKeyboardBindings'" -``` - -Or, to enable/disable it globally at the machine level, run the following commands: - -```powershell -chocolateyguicli feature enable --name="'UseKeyboardBindings'" --global - -chocolateyguicli feature disable --name="'UseKeyboardBindings'" --global -``` - -## Default Value - -The default value for this feature is enabled. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.17.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.17.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/index.md b/input/en-us/chocolatey-gui/setup/configuration/index.md deleted file mode 100644 index 7f63db8c7f..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -Order: 50 -xref: gui-configuration -Title: Configuration -Description: How to configure Chocolatey GUI ---- - -There are two types of configuration which can be applied to Chocolatey GUI. The first is a setting (config) value, which could be a string, or a number, which the user can set. The other is a feature, which can either be turned on or off. Exposing these configuration options is done through the [config]() and [feature]() commands of the chocolateyguicli executable. \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/setup/configuration/settings/default-source-name.md b/input/en-us/chocolatey-gui/setup/configuration/settings/default-source-name.md deleted file mode 100644 index 4da2802a1e..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/settings/default-source-name.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -Order: 10 -xref: default-source-name -Title: Default Source Name -Description: Information on how to use the Default Source Name setting ---- - -By default, when Chocolatey GUI opens it will show the "This PC" source, showing all of the locally installed packages. Depending on your usage of Chocolatey GUI, it may make more sense to default to showing a different source when the application first loads. By setting this configuration option to the name of a configured source, Chocolatey GUI will show this by default when it first opens. If the value of the DefaultSourceName setting doesn't match the name of a configured source, then the "This PC" source will be shown. - - - - - -## Resources - -Below is a short video which shows this configuration setting in action: - -

-

- -
-
-

- -## Example - -To set this configuration parameter, for the currently logged in user, you can run the following: - -```powershell -chocolateyguicli config set --name="'DefaultSourceName'" --value="'chocolatey'" -``` - -Or to set it globally at the machine level, run the following: - -```powershell -chocolateyguicli config set --name="'DefaultSourceName'" --value="'chocolatey'" --global -``` - -## Default Value - -The default value for this setting is an empty string. - -## Availability - -The ability to control this feature from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.18.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.18.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/settings/index.md b/input/en-us/chocolatey-gui/setup/configuration/settings/index.md deleted file mode 100644 index 9e079ddf8f..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/settings/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 10 -xref: gui-configuration-settings -Title: Settings -Description: The available config options for Chocolatey GUI ---- \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/setup/configuration/settings/outdated-packages-cache-duration-in-minutes.md b/input/en-us/chocolatey-gui/setup/configuration/settings/outdated-packages-cache-duration-in-minutes.md deleted file mode 100644 index 4d7db87b1c..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/settings/outdated-packages-cache-duration-in-minutes.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -Order: 20 -xref: outdated-packages-cache-duration-in-minutes -Title: Outdated Packages Cache Duration in Minutes -Description: Information on how to use the Outdated Packages Cache Duration setting ---- - -In an attempt to be as efficient as possible, Chocolatey GUI caches the information about which of the installed -packages are currently outdated. Instead of running the `choco outdated` command every time that information is -requested, the information is instead fetched from the local cache. The length of time that the outdated packages -information is kept can be controlled via this configuration parameter. The default is 60 minutes, which can be -increased as required. - -> :choco-info: **NOTE** -> -> Any time a package operation is completed, i.e. install/uninstall/upgrade, the outdated package information cache will be invalidated. - -## Resources - -Below is a short video which shows this configuration setting in action: - -

-

- -
-
-

- -## Example - -To set this configuration parameter, for the currently logged in user, you can run the following: - -```powershell -chocolateyguicli config set --name="'OutdatedPackagesCacheDurationInMinutes'" --value="'120'" -``` - -Or to set it globally at the machine level, run the following: - -```powershell -chocolateyguicli config set --name="'OutdatedPackagesCacheDurationInMinutes'" --value="'120'" --global -``` - -## Default Value - -The default value for this configuration is 60 minutes. - -## Availability - -The ability to control this setting from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.17.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.17.0. diff --git a/input/en-us/chocolatey-gui/setup/configuration/settings/use-language.md b/input/en-us/chocolatey-gui/setup/configuration/settings/use-language.md deleted file mode 100644 index b8bc692695..0000000000 --- a/input/en-us/chocolatey-gui/setup/configuration/settings/use-language.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -Order: 30 -xref: use-language -Title: Use Language -Description: Information on how to use the Use Language setting ---- - -By default, Chocolatey GUI will use the locale defined on your machine, to translate the various sections of the user -interface. However, there are times when you may want to use a locale other than the one defined on your machine. The -UseLanguage configuration setting allows the user to choose what language (from the list of currently [available languages](xref:use-language#available-languages)), -to use. - -> :choco-info: **NOTE** -> -> This configuration setting appears in a slightly different area of the Chocolatey GUI settings screen -> -> ![Showing the choosing of language within settings](/assets/images/chocolatey-gui/user_interface_settings_language.png "Showing the choosing of language within settings") - -## Example - -To set this configuration parameter, for the currently logged in user, you can run the following: - -```powershell -chocolateyguicli config set --name="'UseLanguage'" --value="'de'" -``` - -Or to set it globally at the machine level, run the following: - -```powershell -chocolateyguicli config set --name="'UseLanguage'" --value="'de'" --global -``` - -See the list of currently [available languages](xref:use-language#available-languages) for the value to use when setting -the language. - -## Available Languages - -Currently, the following languages can be selected: - -- `cs-CZ-` - čeština (Česko) (Czech (Czechia)) -- `de` - Deutsch (German) -- `en` - English (English) -- `en_US` - English (United States) (English (United States)) -- `es` - español (Spanish) -- `fr` - français (French) -- `nl` - Nederlands (Dutch) -- `nb` - norsk bokmål (Norwegian Bokmål) -- `pt` - português (Portuguese) -- `zh_CN` - 中文(中国) (Chinese (Simplified, China)) - -> :choco-info: **NOTE** -> -> Chocolatey GUI only uses languages that have over 60% of the languages strings translated. If your desired language -> isn't in the list above, then feel free to join the [localization effort](xref:gui-localization). - -## Default Value - -The default value for this configuration is the locale defined on your machine if it exists, falling back to English if there is no translation available. - -## Availability - -The ability to control this setting from the Chocolatey GUI Settings screen has existed since Chocolatey GUI v0.20.0. - -The ability to control this feature from the command line using `chocolateyguicli` has existed since Chocolatey GUI -v0.20.0. \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/setup/index.md b/input/en-us/chocolatey-gui/setup/index.md deleted file mode 100644 index f67b5b7c9c..0000000000 --- a/input/en-us/chocolatey-gui/setup/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 20 -xref: gui-setup -Title: Setup -Description: Information on how to install and setup Chocolatey GUI ---- \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/setup/installation.md b/input/en-us/chocolatey-gui/setup/installation.md deleted file mode 100644 index d599253de4..0000000000 --- a/input/en-us/chocolatey-gui/setup/installation.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -Order: 10 -xref: gui-installation -Title: Installation -Description: Instructions on how to install Chocolatey GUI -RedirectFrom: - - en-us/chocolatey-gui/setup/installation/chocolateygui - - en-us/chocolatey-gui/setup/installation/chocolatey-gui ---- - -The easiest way to install Chocolatey GUI is to use Chocolatey. Use the -following command to install the latest version of Chocolatey GUI: - -```powershell -choco install chocolateygui -``` - -## Upgrading Chocolatey GUI - -If you already have Chocolatey GUI installed, you can upgrade to the latest -version using the following command: - -```powershell -choco upgrade chocolateygui -``` - -## Installing Beta Versions of Chocolatey GUI - -Each time a commit is made into the Chocolatey GUI repository, a build is -performed, and the output is pushed to the Chocolatey GUI MyGet feed. If you -are interested in using the very latest version of Chocolatey GUI, you can use -the following command to install it: - -```powershell -choco upgrade chocolateygui --pre --source="'https://myget.org/f/chocolateygui'" -``` - - ## Package Parameters - -The following package parameters can be passed into the `choco install` or `choco upgrade` command to control how the installed version of Chocolatey GUI is configured. - -- `/Global` - Should the configuration change be applied globally, or for the current user -- `/AllowNonAdminAccessToSettings` - Controls whether or not a non-administrator user can access the Settings Screen. NOTE: This feature will only work with Chocolatey for Business and the Chocolatey GUI licensed extension installed - [more info](xref:allow-non-admin-access-to-settings) -- `/DefaultSourceName` - The name of the source which should be shown by default when opening application. NOTE: This configuration setting will only work with Chocolatey for Business and the Chocolatey GUI licensed extension installed - [more info](xref:default-source-name) -- `/DefaultToDarkMode` - Enables/disables whether or not Chocolatey GUI defaults to using dark mode for the Chocolatey GUI User Interface - [more info](xref:default-to-dark-mode) -- `/DefaultToTileViewForLocalSource` - Enables/disables whether or not Chocolatey GUI defaults to tile instead of list view for the local source view - [more info](xref:default-to-tile-view-for-local-source) -- `/DefaultToTileViewForRemoteSource` - Enables/disables whether or not Chocolatey GUI defaults to tile instead of list view for all remote source views - [more info](xref:default-to-tile-view-for-remote-source) -- `/ExcludeInstalledPackages` - Enables/disables whether or not Chocolatey GUI shows packages that are already installed when viewing sources - [more info](xref:exclude-installed-packages) -- `/HideAllRemoteChocolateySources` - Enable/disables whether or not all remote sources are hidden - essentially enabling a read-only view of installed packages. NOTE: This feature will only work with Chocolatey for Business and the Chocolatey GUI licensed extension installed - [more info](xref:hide-all-remote-chocolatey-sources) -- `/HidePackageDownloadCount` - Allows keyboard bindings to be used to interact with different areas of the Chocolatey GUI User Interface - [more info](xref:hide-package-download-count) -- `/HideThisPCSource` - Enable/disables whether or not This PC source is hidden. NOTE: This feature will only work with Chocolatey for Business and the Chocolatey GUI licensed extension installed - [more info](xref:hide-this-pc-source) -- `/OutdatedPackagesCacheDurationInMinutes` - The length of time, in minutes, which Chocolatey GUI will wait before invalidating the cached result of outdated packages for the machine - [more info](xref:outdated-packages-cache-duration-in-minutes) -- `/PreventAllPackageIconDownloads` - Enables/disables whether Chocolatey GUI will attempt to download the icons for packages. NOTE: This feature will only work with Chocolatey for Business and the Chocolatey GUI licensed extension installed - [more info](xref:prevent-all-package-icon-downloads) -- `/PreventAutomatedOutdatedPackagesCheck` - Prevents automated check for outdated packages on startup - [more info](xref:prevent-automated-outdated-packages-check) -- `/PreventPreload` - Prevents preloading results with a blank search when opening the remote source view - [more info](xref:prevent-preload) -- `/PreventUsageOfUpdateAllButton` - Enables/disables whether the Update All button is visible. NOTE: This feature will only work with Chocolatey for Business and the Chocolatey GUI licensed extension installed - [more info](xref:prevent-usage-of-update-all-button) -- `/ShowAdditionalPackageInformation` - Show additional package information on Local and Remote views - [more info](xref:show-additional-package-information) -- `/ShowAggregatedSourceView` - Enables/disables whether or not Chocolatey GUI shows an additional source combining all sources into one location - [more info](xref:show-aggregated-source-view) -- `/ShowConsoleOutput` - Enables/disables whether or not Chocolatey GUI shows output from the commands being executed when a job is running - [more info](xref:show-console-output) -- `/UseDelayedSearch` - Enables/disables whether or not Chocolatey GUI uses a live search, which returns results after a short delay without clicking the search button - [more info](xref:use-delayed-search) -- `/UseKeyboardBindings` - Allows keyboard bindings to be used to interact with different areas of the Chocolatey GUI User Interface - [more info](xref:use-keyboard-bindings) -- `/UseLanguage` - The preferred language for Chocolatey GUI. Defaults to Windows System Locale - [more info](xref:use-language) - -As an example, the following installation command could be used to enable ShowConsoleOutput to ensure UseDelayedSearch is disabled, and set the output cache to 120 minutes: - -``` -choco install chocolateygui --params="'/ShowConsoleOutput=$true /UseDelayedSearch=$false /OutdatedPackagesCacheDurationInMinutes=120'" -``` - -If you wanted to set these options globally so that all users on the machine got these values, run the following: - -``` -choco install chocolateygui --params="'/ShowConsoleOutput=$true /UseDelayedSearch=$false /OutdatedPackagesCacheDurationInMinutes=120 /Global'" -``` \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/setup/uninstallation.md b/input/en-us/chocolatey-gui/setup/uninstallation.md deleted file mode 100644 index 4e26278654..0000000000 --- a/input/en-us/chocolatey-gui/setup/uninstallation.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -Order: 20 -xref: gui-uninstallation -Title: Uninstallation -Description: Instructions on how to uninstall Chocolatey GUI -RedirectFrom: - - en-us/chocolatey-gui/setup/uninstallation/chocolatey-gui ---- - -Chocolatey GUI can be easily uninstalled using the following command: - -```powershell -choco uninstall chocolateygui -``` \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/about/credits.md b/input/en-us/chocolatey-gui/user-interface/about/credits.md deleted file mode 100644 index e3e302e6bd..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/about/credits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -Order: 20 -xref: gui-credits -Title: Credits -Description: Information about tools, software, and frameworks that are used to create Chocolatey GUI ---- - -The credits screen provides information about the different tools, frameworks and open source software that is used to -make the Chocolatey GUI application, as well as information on the folks who work on creating it. - -![About Credits Screen](/assets/images/chocolatey-gui/user_interface_about_credits.png "About Credits Screen") diff --git a/input/en-us/chocolatey-gui/user-interface/about/history.md b/input/en-us/chocolatey-gui/user-interface/about/history.md deleted file mode 100644 index 9bb614ad72..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/about/history.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -Order: 10 -xref: gui-history -Title: History -Description: Information about the evolution of Chocolatey GUI ---- - -The history screen within Chocolatey GUI gives a brief history of the application, and how it has evolved over the -years. - -![About History Screen](/assets/images/chocolatey-gui/user_interface_about_history.png "About History Screen") diff --git a/input/en-us/chocolatey-gui/user-interface/about/index.md b/input/en-us/chocolatey-gui/user-interface/about/index.md deleted file mode 100644 index 33f36d1402..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/about/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -Order: 30 -xref: gui-about -Title: About -Description: Find out information about the Chocolatey GUI application ---- - -The About screen is where you can find information about Chocolatey GUI, including the history of the project, information -about what 3rd party libraries are used by Chocolatey GUI, as well as the release notes for the current version. \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/about/release-notes.md b/input/en-us/chocolatey-gui/user-interface/about/release-notes.md deleted file mode 100644 index 0227a11175..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/about/release-notes.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -Order: 30 -xref: gui-release-notes -Title: Release Notes -Description: Information about what has changed in the current release of Chocolatey GUI ---- - -The release notes screen provides information about the different bugs, features, improvements, etc. that have been made -in the current version of the Chocolatey GUI application. - -![About Release Notes Screen](/assets/images/chocolatey-gui/user_interface_about_release_notes.png "About Release Notes Screen") diff --git a/input/en-us/chocolatey-gui/user-interface/index.md b/input/en-us/chocolatey-gui/user-interface/index.md deleted file mode 100644 index 817b929316..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -Order: 30 -xref: gui-user-interface -Title: User Interface -Description: How to use the Chocolatey GUI User Interface ---- - -The Chocolatey GUI interface is relatively simple, and this section of the documentation will walk through how to interact with the different sections. \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/actions/check-for-outdated.md b/input/en-us/chocolatey-gui/user-interface/main-window/actions/check-for-outdated.md deleted file mode 100644 index 42eea48a73..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/actions/check-for-outdated.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -Order: 20 -xref: check-for-outdated -Title: Check for outdated packages -Description: Information on checking for outdated packages ---- - -Chocolatey GUI, by default, will check for installed packages that are currently outdated (based on available sources) when the application first loads. However, this can be turned of using the [Prevent Automated Outdated Packages Check](xref:prevent-automated-outdated-packages-check) feature, or there can be changes to packages outside of Chocolatey GUI. When these situations occur, you can manually invoke the check for outdated packages using the following button: - -![Show where the check for outdated packages button is located within the User Interface](/assets/images/chocolatey-gui/user_interface_main-window_action_check-for-outdated.png "Show where the check for outdated packages button is located within the User Interface") - -> :choco-info: **NOTE** -> -> This button exists when looking at both local and remote sources \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/actions/darkmode.md b/input/en-us/chocolatey-gui/user-interface/main-window/actions/darkmode.md deleted file mode 100644 index 064f22057f..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/actions/darkmode.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -Order: 70 -xref: gui-darkmode -Title: Toggle Light/Dark Mode -Description: Information about changing between light and dark mode ---- - -Chocolatey GUI provides the ability to toggle between light mode (the default selection) and a dark mode within the application. - -The following screenshot illustrates where the toggle button is located: - -![Show where the light/dark toggle is located within the User Interface](/assets/images/chocolatey-gui/user_interface_main-window_action_toggle_mode_1.png "Show where the light/dark toggle is located within the User Interface") - -This is what the User Interface looks like when light mode is selected: - -![Show what the User Interface looks like when light mode is selected](/assets/images/chocolatey-gui/user_interface_main-window_action_toggle_mode_2.png "Show what the User Interface looks like when light mode view is selected") - -This is what the User Interface looks like when dark mode is selected: - -![Show what the User Interface looks like when dark mode is selected](/assets/images/chocolatey-gui/user_interface_main-window_action_toggle_mode_3.png "Show what the User Interface looks like when dark mode is selected") - -If required, the [default selection for light/dark mode](xref:default-to-dark-mode) can be modified to your personal liking. - -> :choco-info: **NOTE** -> -> This button exists when using the entire application \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/actions/export.md b/input/en-us/chocolatey-gui/user-interface/main-window/actions/export.md deleted file mode 100644 index 014c3266bd..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/actions/export.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -Order: 50 -xref: gui-export -Title: Export -Description: Information about exporting the currently installed packages ---- - -Chocolatey GUI provides the ability to export all the currently installed packages (including the version number) from the current machine. This information is exported into a *.config file, which can then be used to install all packages again, on another machine. - -For example, lets imagine that you wanted to completely reset your current machine, and re-install the operating system. You could use the export button to exported all the currently installed packages, then store the generated file somewhere safe, re-install the operating system, and then get back to the exact same place as you are now with the list of packages. - -The following screenshot illustrates where the Export button is located: - -![Show where the Export button is located within the User Interface](/assets/images/chocolatey-gui/user_interface_main-window_action_export_1.png "Show where the Export button is located within the User Interface") - -Once pushed, you will be prompted for the file name that you would like to use, and where you want the file saved: - -![Show the save file dialog that is opened when the Export button is clicked](/assets/images/chocolatey-gui/user_interface_main-window_action_export_2.png "Show the save file dialog that is opened when the Export button is clicked") - -Once it is complete, you will have a file that looks like the following: - -![Show the contents of the file that is generated when the Export operation is completed](/assets/images/chocolatey-gui/user_interface_main-window_action_export_3.png "Show the contents of the file that is generated when the Export operation is completed") - -It would then be possible to take this file onto another machine and then run the following choco command to re-install all the packages again: - -```powershell -choco install -``` - -> :choco-info: **NOTE** -> -> This button only exists when browsing the local source, i.e. `This PC` \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/actions/index.md b/input/en-us/chocolatey-gui/user-interface/main-window/actions/index.md deleted file mode 100644 index 7f7f4fa5d3..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/actions/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -Order: 50 -xref: gui-main-window-actions -Title: Actions -Description: Information about the top level actions that can be performed in Chocolatey GUI ---- - -There are several top level actions that can be performed from the Chocolatey GUI main window. Lets take a look at each of these, and see what they can do. \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/actions/refresh.md b/input/en-us/chocolatey-gui/user-interface/main-window/actions/refresh.md deleted file mode 100644 index 11208f37e4..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/actions/refresh.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -Order: 30 -xref: gui-refresh -Title: Refresh -Description: Information on refreshing the current packages list ---- - -Chocolatey GUI, by default, will automatically check for the currently installed packages, and will fetch the first page of results when looking at remote sources, when navigating to a source when the application first loads. However, this functionality can be configured using the [Prevent Preload](xref:prevent-preload) feature, or there can be changes to packages outside of Chocolatey GUI. When these situations occur, you can manually refresh the current list of packages using the following button: - -![Show where the refresh packages button is located within the User Interface](/assets/images/chocolatey-gui/user_interface_main-window_action_refresh-packages.png "Show where the refresh packages button is located within the User Interface") - -> :choco-info: **NOTE** -> -> This button exists when looking at both local and remote sources \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/actions/search.md b/input/en-us/chocolatey-gui/user-interface/main-window/actions/search.md deleted file mode 100644 index 7741cfc483..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/actions/search.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -Order: 10 -xref: gui-search -Title: Search -Description: Information on how to search for Chocolatey packages ---- - -There are two search boxes within the Chocolatey GUI interface. The first is when looking at local packages (within the `This PC` section): - -![Show search box for local packages](/assets/images/chocolatey-gui/user_interface_main-window_action_search_1.png "Show search box for remote packages") - -and the second is within any remote source view (for example the Chocolatey Community Repository): - -![Show search box for remote packages](/assets/images/chocolatey-gui/user_interface_main-window_action_search_2.png "Show search box for remote packages") - -Essentially, these search boxes perform the same operation, but there are slight differences with how they operate. - -## Local Packages Search - -When searching for a package that is installed locally on your machine, all that is required is to type the search string into the box, and the results will be shown immediately. - -## Remote Packages Search - -By default, in order to start a search, it is necessary to first enter the search string and then either click the magnifying glass icon, or to press the enter key on your keyboard. - -![Show magnifying glass for initiating search](/assets/images/chocolatey-gui/user_interface_main-window_action_search_3.png "Show magnifying glass for initiating search") - -If you want to begin the search immediately after you finish typing, you can activate the [Use Delayed Search](xref:use-delayed-search) feature. - -## Additional package filtering - -In addition to the search string that you can provide when searching for a package, there are additional filters that you can apply to the search results. These differ between searching for local packages compared to remote packages. - -### Filtering local packages search - -When searching for local packages, it is possible to use the following additional filtering terms: - -- Match Word Exactly -- Show Only Packages with Updates - -![Show additional filtering options for local packages](/assets/images/chocolatey-gui/user_interface_main-window_action_search_4.png "Show additional filtering options for local packages") - -### Filtering remote packages search - -When searching for remote packages, it is possible to use the following additional filtering terms: - -- All Versions -- Include Prerelease -- Match Word Exactly -- Popularity - -![Show additional filtering options for remote packages](/assets/images/chocolatey-gui/user_interface_main-window_action_search_5.png "Show additional filtering options for remote packages") \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/actions/tileview.md b/input/en-us/chocolatey-gui/user-interface/main-window/actions/tileview.md deleted file mode 100644 index 081f8f1483..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/actions/tileview.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -Order: 60 -xref: gui-tileview -Title: Switch Tile/List View -Description: Information about changing how packages are displayed ---- - -Chocolatey GUI provides the ability to toggle between tile view (the default selection) and a list view for both local and remote sources within the application. - -The following screenshot illustrates where the buttons to toggle between one view and the other are located: - -![Show where the tile/list view toggle is located within the User Interface](/assets/images/chocolatey-gui/user_interface_main-window_action_switch_display_1.png "Show where the tile/list view toggle is located within the User Interface") - -This is what the User Interface looks like when the tile view is selected: - -![Show what the User Interface looks like when tile view is selected](/assets/images/chocolatey-gui/user_interface_main-window_action_switch_display_2.png "Show what the User Interface looks like when tile view is selected") - -This is what the User Interface looks like when the list view is selected: - -![Show what the User Interface looks like when list view is selected](/assets/images/chocolatey-gui/user_interface_main-window_action_switch_display_3.png "Show what the User Interface looks like when list view is selected") - -If required, the [default selection for local sources](xref:default-to-tile-view-for-local-source) and the [default selection for remote sources](xref:default-to-tile-view-for-remote-source) can be modified to your personal liking. - -> :choco-info: **NOTE** -> -> This button exists when looking at both local and remote sources \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/actions/update-all.md b/input/en-us/chocolatey-gui/user-interface/main-window/actions/update-all.md deleted file mode 100644 index cbdf2d06d8..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/actions/update-all.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -Order: 40 -xref: gui-update-all -Title: Update All -Description: Information about updating all Chocolatey Packages ---- - -By default, when Chocolatey GUI first opens it will check for all currently outdated packages based on the currently configured sources (this can be configured via the [Prevent Automated Outdated Packages Check](xref:prevent-automated-outdated-packages-check) feature). Once identified as outdated, you have the option of right clicking on an individual package to update it, or you can go into the details page for the package and click the update button that is located there. However, if you want to update all outdated packages at the same time, you can use the update all button: - -![Show where the update all button is located within the User Interface](/assets/images/chocolatey-gui/user_interface_main-window_action_update-all_1.png "Show where the update all button is located within the User Interface") - -When there are no packages that are currently outdated, the button will be disabled and will show a message in the tooltip that this operation cannot currently be performed: - -![Show the update all button being disabled as no action can be taken](/assets/images/chocolatey-gui/user_interface_main-window_action_update-all_2.png "Show the update all button being disabled as no action can be taken") - -> :choco-info: **NOTE** -> -> This button only exists when browsing the local source, i.e. `This PC` - -> :choco-info: **NOTE** -> -> If required, it is possible to remove the Update All button via the [PreventUsageOfUpdateAllButton](xref:prevent-usage-of-update-all-button) feature. \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/index.md b/input/en-us/chocolatey-gui/user-interface/main-window/index.md deleted file mode 100644 index f8acf02b02..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -Order: 10 -xref: gui-main-window -Title: Main Window -Description: The primary interface that is used within Chocolatey GUI ---- - -The primary user interface for Chocolatey GUI is split into a number of sections. - -![The primary user interface for Chocolatey GUI](/assets/images/chocolatey-gui/user_interface_main-window_sections.png "The primary user interface for Chocolatey GUI") - -1. The top navigation menu, which allows you to navigate to the [settings](xref:gui-settings) and [about](xref:gui-about) -pages, and in addition to toggle whether or not to use the [dark or light mode](xref:gui-darkmode). -1. The main action bar, which allows you to [search](xref:gui-search), [check for outdated packages](xref:check-for-outdated), [refresh the current list of packages](xref:gui-refresh), [update all packages](xref:gui-update-all), [export currently installed packages](xref:gui-export), and to toggle between [list or grid view](xref:gui-tileview). -1. The `This PC` to the [local source](xref:gui-local-source) tab -1. One or more [remote sources](xref:gui-remote-source), based on current Chocolatey [source configuration](xref:gui-sources) -1. Displays the current version number of Chocolatey GUI -1. Shows the current package list, based on the selected source (either local, or a remote one). Double clicking on a package, right clicking and selecting `Details` in the context menu, will take you to the [package details page](xref:gui-package-details). \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/local-source.md b/input/en-us/chocolatey-gui/user-interface/main-window/local-source.md deleted file mode 100644 index 8243475825..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/local-source.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -Order: 20 -xref: gui-local-source -Title: Local Source -Description: Information about displaying of locally installed packages ---- - -The "This PC" source, also known as a local source, is the first source that is shown by default when Chocolatey GUI first -opens, and it shows all the currently installed Chocolatey packages. It is the visual equivalent of running the `choco -list` command in Chocolatey CLI v2, and `choco list -lo` in Chocolatey CLI v1, and paging the results that are displayed. - -![The This PC Source showing currently installed Chocolatey packages](/assets/images/chocolatey-gui/feature_hide_this_pc_source_disabled.png "The This PC Source showing currently installed Chocolatey packages") - -It is possible to show this view in both tile and list format, and this can be controlled through the [toggle switch](xref:gui-tileview), or -by setting the [Default to Tile View for Local Source](xref:default-to-tile-view-for-local-source) feature to the required setting. - -In addition, you may want to use the [Prevent Automated Outdated Packages Check](xref:prevent-automated-outdated-packages-check) feature, to prevent Chocolatey GUI calculating what packages are outdated each time Chocolatey GUI opens. It is possible to directly trigger this check using the [Check For Outdated](xref:check-for-outdated) action. - -From the local source view, either by navigating to the [package details page](xref:gui-package-details), or by activating the context menu for the -required package, it is possible to perform one of the [available actions](xref:gui-package-details-actions) for a package. - -The local source view can be turned off using the [Hide This PC Source](xref:hide-this-pc-source) feature. **NOTE:** This is a commercial feature that requires the use of the [Chocolatey GUI Licensed Extension](xref:chocolatey-gui-licensed-extension). \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/index.md b/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/index.md deleted file mode 100644 index ed97aecf04..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -Order: 40 -xref: gui-package-details-actions -Title: Actions -Description: Information about top level actions that can be completed from Package Details screen ---- - -Depending on the current state of the selected package, i.e. is it installed, outdated, etc, different actions can be -performed on the package. This sections aims to explain the different actions that can be taken. \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/install-advanced.md b/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/install-advanced.md deleted file mode 100644 index 1bfb8e3aff..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/install-advanced.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -Order: 20 -xref: gui-package-details-actions-install-advanced -Title: Install Advanced -Description: Information on how to use the Install Advanced action ---- - -During normal execution, Chocolatey GUI performs a standard installation of a package, specifying only the package version -and the Source to install from. For most installations, this is all that is required. - -There are times though when additional parameters need to be set for a package. - -For example, a package may have one or more package parameters, to allow for controlling whether desktop shortcuts are -created, or what entries should appear on the Windows path. In order to set these values so that they are passed when -installing the package, you have to make use of the Install Advanced window: - -![Modal window showing the ability to set install arguments when installing a package](/assets/images/chocolatey-gui/user_interface_main-window_package-details_install-advanced.png "Modal window showing the ability to set install arguments when installing a package") - -All of the command line options (with the exception of the additional log file) that you can specify when running -choco.exe directly, can be set within this window. - -The settings are grouped into sections: - -- Install Options -- Advanced Options -- Dependency Options -- Checksum Option \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/install.md b/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/install.md deleted file mode 100644 index bcacd49b70..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/install.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -Order: 30 -xref: gui-package-details-actions-install -Title: Install -Description: Information on how to use the Install action -ShowInNavBar: false -ShowInSideBar: false ---- - -> :choco-warning: **WARNING** -> -> This is a Work in Progress. Please check back later \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/pin.md b/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/pin.md deleted file mode 100644 index c47912680a..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/pin.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -Order: 40 -xref: gui-package-details-actions-pin -Title: Pin -Description: Information on how to use the Pin action -ShowInNavBar: false -ShowInSideBar: false ---- - -> :choco-warning: **WARNING** -> -> This is a Work in Progress. Please check back later \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/reinstall.md b/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/reinstall.md deleted file mode 100644 index 6d41586450..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/reinstall.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -Order: 60 -xref: gui-package-details-actions-reinstall -Title: Reinstall -Description: Information on how to use the Reinstall action -ShowInNavBar: false -ShowInSideBar: false ---- - -> :choco-warning: **WARNING** -> -> This is a Work in Progress. Please check back later \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/uninstall.md b/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/uninstall.md deleted file mode 100644 index 062883eb7f..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/uninstall.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -Order: 70 -xref: gui-package-details-actions-uninstall -Title: Uninstall -Description: Information on how to use the Uninstall action -ShowInNavBar: false -ShowInSideBar: false ---- - -> :choco-warning: **WARNING** -> -> This is a Work in Progress. Please check back later \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/unpin.md b/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/unpin.md deleted file mode 100644 index 32fd91ec55..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/unpin.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -Order: 50 -xref: gui-package-details-actions-unpin -Title: Unpin -Description: Information on how to use the Unpin action -ShowInNavBar: false -ShowInSideBar: false ---- - -> :choco-warning: **WARNING** -> -> This is a Work in Progress. Please check back later \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/update.md b/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/update.md deleted file mode 100644 index e25e106c1f..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/update.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -Order: 80 -xref: gui-package-details-actions-update -Title: Update -Description: Information on how to use the Update action -ShowInNavBar: false -ShowInSideBar: false ---- - -> :choco-warning: **WARNING** -> -> This is a Work in Progress. Please check back later \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/view-package-arguments.md b/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/view-package-arguments.md deleted file mode 100644 index 365d9e4757..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/actions/view-package-arguments.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -Order: 10 -xref: gui-package-details-actions-view-package-arguments -Title: View Package Arguments -Description: Information on how to use the View Package Arguments action ---- - -Each time a package is installed, either via Chocolatey or Chocolatey GUI, the arguments that were passed into the -command are recorded, so that they can be re-used when performing an upgrade of the package. - -> :choco-warning: **WARNING** -> -> The useRememberedArgumentsForUpgrades feature of Chocolatey needs to be enabled for this ability to be used. - -It can be useful to view the remembered arguments that Chocolatey has stored for a given package version. - -Clicking the `View Package Arguments` button while on the package details page for a package will show a modal window -populated with the arguments. For example: - -![Modal window showing the remembered package arguments for the current package version](/assets/images/chocolatey-gui/user_interface_main-window_package-details_view-package-arguments.png "Modal window showing the remembered package arguments for the current package version") - -If there are no remembered arguments for the current package version, this will also be shown: - -![Modal window showing there were no remembered package arguments for the current package version](/assets/images/chocolatey-gui/user_interface_main-window_package-details_view-package-arguments_empty.png "Modal window showing there were no remembered package arguments for the current package version") \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/index.md b/input/en-us/chocolatey-gui/user-interface/main-window/package-details/index.md deleted file mode 100644 index 82ca3c9385..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/package-details/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -Order: 40 -xref: gui-package-details -Title: Package Details -Description: Information about displaying detailed information about a specific package ---- - -After either double clicking on a package, or choosing details from the context menu, from the [main window](xref:gui-main-window), -the details for the selected package will be shown. This includes information such as: - -- Package Id -- Version -- Last update -- External links provided by the package maintainer -- Description -- Release notes -- Software Authors -- Package Maintainers (If available) -- Downloads for the version, and total downloads -- Size of the package -- Package Dependencies - -In addition, depending on the current state of the package, different [actions](xref:gui-package-details-actions) can be performed on the package. - -![The package details user interface for Chocolatey GUI](/assets/images/chocolatey-gui/user_interface_main-window_package-details.png "The package details user interface for Chocolatey GUI") \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/main-window/remote-source.md b/input/en-us/chocolatey-gui/user-interface/main-window/remote-source.md deleted file mode 100644 index 70d8e560c2..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/main-window/remote-source.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -Order: 30 -xref: gui-remote-source -Title: Remote Source -Description: Information about displaying available packages from remote sources ---- - -Any [Chocolatey source](xref:gui-sources) that is configured will show as a remote source in the Chocolatey GUI [main window](xref:gui-main-window). When selected, either directly through the user interface, or via a [keyboard shortcut](xref:use-keyboard-bindings), the available packages from that source will be fetched, and shown. - -It is the visual equivalent of running the `choco list --source https://community.chocolatey.org` command, and paging the results that are displayed. - -There are various features that can be used to configure how remote sources work, including: - -- [Exclude Install Packages](xref:exclude-installed-packages) -- [Prevent Preload](xref:prevent-preload) -- [Show Aggregated Source View](xref:show-aggregated-source-view) - -![Remote Source showing packages from the Chocolatey Community Repository](/assets/images/chocolatey-gui/feature_default_tile_view_remote_enabled.png "Remote Source showing packages from the Chocolatey Community Repository") - -It is possible to show this view in both tile and list format, and this can be controlled through the [toggle switch](xref:gui-tileview), or -by setting the [Default to Tile View for Local Source](xref:default-to-tile-view-for-remote-source) feature to the required setting. - -From any remote source view, either by navigating to the [package details page](xref:gui-package-details), or by activating the context menu for the -required package, it is possible to perform one of the [available actions](xref:gui-package-details-actions) for a package. - -All remote sources can be turned off using the [Hide All Remote Chocolatey Sources](xref:hide-all-remote-chocolatey-sources) feature. **NOTE:** This is a commercial feature that requires the use of the [Chocolatey GUI Licensed Extension](xref:chocolatey-gui-licensed-extension). \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/settings/actions/index.md b/input/en-us/chocolatey-gui/user-interface/settings/actions/index.md deleted file mode 100644 index 8bbac17fa2..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/settings/actions/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -Order: 40 -xref: gui-settings-actions -Title: Actions -Description: Information about top level actions that can be completed from Settings screen ---- - -Within the Chocolatey GUI Settings screen, there are some top level actions that can be completed for the application. These icon purging the different caches that are used. In addition to being able to trigger these from within Chocolatey GUI, it is also possible to use the chocolateyguicli command to accomplish the same thing. Information on this command can be found [here](xref:gui-purge-command). \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/settings/actions/purge-icons.md b/input/en-us/chocolatey-gui/user-interface/settings/actions/purge-icons.md deleted file mode 100644 index 5ae33c2852..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/settings/actions/purge-icons.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -Order: 20 -xref: gui-purge-icons -Title: Purge Icons -Description: Information about purging icons ---- - -To prevent downloading the same application icon multiple times, Chocolatey GUI caches the icon that is found for each -package, both those that are installed locally, as well as those from remote sources. These are stored locally on disk -and will remain cached indefinitely. If/when required, you can click the `Purge Icons` button to completely clear the -icon cache, and it will begin to be built up again. - -![Settings Actions Purge Icons](/assets/images/chocolatey-gui/user_interface_settings_actions_purge_icons.png "Settings Actions Purge Icons") - -In addition to purging the cache from within the Chocolatey GUI application, it is also possible to do this using the -`chocolateyguicli` executable. More information on doing this can be found [here](xref:gui-purge-command). diff --git a/input/en-us/chocolatey-gui/user-interface/settings/actions/purge-outdated-packages.md b/input/en-us/chocolatey-gui/user-interface/settings/actions/purge-outdated-packages.md deleted file mode 100644 index 424ea04a71..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/settings/actions/purge-outdated-packages.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -Order: 10 -xref: gui-purge-outdated-packages -Title: Purge Outdated Packages -Description: Information about purging outdated packages ---- - -In order to prevent requesting the same information again and again from Chocolatey, Chocolatey GUI caches information -about the outdated packages which are currently installed on the machine. It uses this information to display an -outdated banner on the package within the Chocolatey GUI application. By default, this cache is kept for 60 minutes, -and you can change this configuration value if required. If, for whatever reason, you need to purge this cache, you -can do so using the `Purge Outdated Packages` button. When a Chocolatey operation such as `install`, `upgrade`, or -`uninstall` is performed, the Outdated Packages cache will be invalidated. - -![Settings Actions Purge Outdated Packages](/assets/images/chocolatey-gui/user_interface_settings_actions_purge_outdated_packages.png "Settings Actions Purge Outdated Packages") - -In addition to purging the cache from within the Chocolatey GUI application, it is also possible to do this using the -`chocolateyguicli` executable. More information on doing this can be found [here](xref:gui-purge-command). diff --git a/input/en-us/chocolatey-gui/user-interface/settings/chocolatey-gui.md b/input/en-us/chocolatey-gui/user-interface/settings/chocolatey-gui.md deleted file mode 100644 index b540fe1f52..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/settings/chocolatey-gui.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -Order: 10 -xref: settings-gui -Title: Chocolatey GUI -Description: Settings for Chocolatey GUI ---- - -The Chocolatey GUI Settings screen allows the user to toggle on and off the various features that the application -supports, as well as to set values for the specific configuration values that exist within the application. Normally, -once changed, the feature or configuration value changes takes immediate effect, but it may require an application -restart to take effect. - -There are search boxes that allow you to type the name of a feature, or a setting, and the list will be filtered down -to only match entries with the search phrase in either the display name or the configuration name. - -![Settings Chocolatey GUI](/assets/images/chocolatey-gui/user_interface_settings_chocolatey_gui.png "Settings Chocolatey GUI") - -For more information about the individual features and settings, see the corresponding section below: - -## Features - - - -## Settings - - diff --git a/input/en-us/chocolatey-gui/user-interface/settings/chocolatey.md b/input/en-us/chocolatey-gui/user-interface/settings/chocolatey.md deleted file mode 100644 index f6ecf61d5a..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/settings/chocolatey.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -Order: 20 -xref: settings-chocolatey -Title: Chocolatey -Description: Settings for Chocolatey ---- - -The Chocolatey Settings screen allow the user to toggle on and off the various features that Chocolatey supports, as -well as to set values for the specific configuration values that exist for Chocolatey. - -There are search boxes that allow you to type the name of a feature, or a setting, and the list will be filtered down -to only match entries with the search phrase in either the display name or the configuration name. - -![Settings Chocolatey](/assets/images/chocolatey-gui/user_interface_settings_chocolatey.png "Settings Chocolatey") - -Changing the values in this screen is the same as directly calling the `choco feature` or `choco config` commands. For -more information about exactly what these settings are, and what they can be used for, see the -[Chocolatey documentation](https://chocolatey.org/docs/chocolatey-configuration). diff --git a/input/en-us/chocolatey-gui/user-interface/settings/index.md b/input/en-us/chocolatey-gui/user-interface/settings/index.md deleted file mode 100644 index 2eb3febc01..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/settings/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -Order: 20 -xref: gui-settings -Title: Settings -Description: Modify the settings for Chocolatey GUI ---- - -The Settings screen is where you can view and modify the different configuration options for both Chocolatey GUI as well -as Chocolatey. \ No newline at end of file diff --git a/input/en-us/chocolatey-gui/user-interface/settings/sources/add.md b/input/en-us/chocolatey-gui/user-interface/settings/sources/add.md deleted file mode 100644 index 3913592600..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/settings/sources/add.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -Order: 10 -xref: gui-add-source -Title: Add Source -Description: Information on how to add a source using Chocolatey GUI ---- - -To add a new source through Chocolatey GUI simply click the `NEW` button. This will clear out all the fields: - -- Id -- Source -- Username -- Certificate -- Priority -- Is Disabled -- Is Self Service -- Is Proxy Bypassed -- Visible to Admins Only - -ready to be populated for the new source. - -![Showing the user interface when adding a new source](/assets/images/chocolatey-gui/user_interface_settings_sources_add.png "Showing the user interface when adding a new source") - -Fill in all these details, and once completed, click the `SAVE` button. The new source will then appear in the Sources section at the top of the screen. - -## Resources - -Below is a short video which shows how to add a source: - -

-

- -
-
-

diff --git a/input/en-us/chocolatey-gui/user-interface/settings/sources/delete.md b/input/en-us/chocolatey-gui/user-interface/settings/sources/delete.md deleted file mode 100644 index 3a7277ef89..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/settings/sources/delete.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -Order: 30 -xref: gui-delete-source -Title: Delete Source -Description: Information on how to delete a source using Chocolatey GUI ---- - -To remove a source select it in the `Sources` section at the top of the screen and then click the `REMOVE` button. - -![Showing the user interface when removing a source](/assets/images/chocolatey-gui/user_interface_settings_sources_remove.png "Showing the user interface when removing a source") - -The source will be removed and the `Sources` section will be updated with the remaining sources. - -## Resources - -Below is a short video which shows how to delete a source: - -

-

- -
-
-

diff --git a/input/en-us/chocolatey-gui/user-interface/settings/sources/edit.md b/input/en-us/chocolatey-gui/user-interface/settings/sources/edit.md deleted file mode 100644 index a4e24781e6..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/settings/sources/edit.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -Order: 20 -xref: gui-edit-source -Title: Edit Source -Description: Information on how to edit a source using Chocolatey GUI ---- - -To edit an existing source through Chocolatey GUI simply click on the source in the `Sources` section. The details of this source will then be populated in the lower half of the screen, and all of these fields can then be edited: - -- Id -- Source -- Username -- Certificate -- Priority -- Is Disabled -- Is Self Service -- Is Proxy Bypassed -- Visible to Admins Only - -![Showing the user interface when editing an existing source](/assets/images/chocolatey-gui/user_interface_settings_sources_edit_1.png "Showing the user interface when editing an existing source") - -Update all these details, and once completed, click the `SAVE` button. The updated source will then refresh in the Sources section at the top of the screen. - -> :choco-info: **NOTE** -> -> If attempting to edit the built-in `chocolatey.licensed` source, only certain fields are allowed to be modified, and this will be reflected within the user interface -> -> ![Showing the user interface when attempting to edit chocolatey.licensed source](/assets/images/chocolatey-gui/user_interface_settings_sources_edit_2.png "Showing the user interface when attempting to edit chocolatey.licensed source") - -## Resources - -Below is a short video which shows how to edit a source: - -

-

- -
-
-

diff --git a/input/en-us/chocolatey-gui/user-interface/settings/sources/index.md b/input/en-us/chocolatey-gui/user-interface/settings/sources/index.md deleted file mode 100644 index 22e661bd39..0000000000 --- a/input/en-us/chocolatey-gui/user-interface/settings/sources/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -Order: 30 -xref: gui-sources -Title: Sources -Description: Configure the sources used by Chocolatey GUI ---- - -Within the Sources section of Settings screen, it is possible to view, add, edit and delete the different sources that are used by both Chocolatey GUI and Chocolatey. - -![Showing the Sources screen within settings](/assets/images/chocolatey-gui/user_interface_settings_sources.png "Showing the Sources screen within settings") \ No newline at end of file diff --git a/input/en-us/chocolatey-install-ps1.md b/input/en-us/chocolatey-install-ps1.md deleted file mode 100644 index f5624eaea1..0000000000 --- a/input/en-us/chocolatey-install-ps1.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -Order: 71 -xref: chocolatey-install-ps1 -Title: ChocolateyInstall PowerShell Script -Description: Information about the chocolateyinstall.ps1 file which is used to by Chocolatey to install the package contents -RedirectFrom: docs/chocolatey-install-ps1 -ShowInNavbar: false -ShowInSidebar: false ---- - -Chocolatey uses PowerShell as a package install provider and will look for this file in the package. If it finds it, it will execute the contents of the file, attaching the helper modules. Check out the [Helper Reference](xref:powershell-reference) for more information on each of the helpers you can include. - -It really is just PowerShell, so you can use regular PowerShell here and it should run fine. - -> :choco-info: **NOTE** -> -> Please maintain compatibility with Posh v2. Not every OS we support is on Posh v2 (nor comes OOB with Posh v3+). It's best to work with the widest compatibility of systems out there. - -## When is the script triggered? - -If present in a package, the `ChocolateyInstall.ps1` script will be triggered at the following points: - -* When a package is installed for the first time, after the package contents have been extracted. -* In an [Upgrade](xref:choco-command-upgrade) scenario, the install script for the new package will be run after any `chocolateyBeforeModify.ps1` script associated with the previous version of the package. - -### Example? - -This is what it takes to install [StExBar](https://community.chocolatey.org/packages/stexbar): - -```powershell -$name = 'StExBar' -$url = 'http://stexbar.googlecode.com/files/StExBar-1.8.3.msi' -$url64 = 'http://stexbar.googlecode.com/files/StExBar64-1.8.3.msi' -$silent = '/quiet' - -Install-ChocolateyPackage $name 'msi' $silent $url $url64 -``` - -The Install-ChocolateyPackage helper uses the url, msi, and silent args to download and silently install and update StExBar. diff --git a/input/en-us/chocolatey-story.md b/input/en-us/chocolatey-story.md deleted file mode 100644 index 19f19d2dcd..0000000000 --- a/input/en-us/chocolatey-story.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 72 -xref: chocolatey-story -Title: Story of Bob and Richard -Description: Background information about where the idea for Chocolatey came from -RedirectFrom: docs/chocolatey-story -ShowInNavbar: false -ShowInSidebar: false ---- - -Let’s start with a story. Two guys, Bob and Richard (whose names have been changed to protect the innocent) need to get their computers ready to do some development work with [Git](https://git-scm.com/). Neither Bob or Richard have worked with Git before. This is a story about the process they each go through to get Git. - -Richard goes off to research. After a while he learns the tool he wants to install for Windows is Git for Windows. He searches, downloads the latest version and goes to install it. He realizes he downloaded the wrong architecture and starts over. He may not have his settings set up properly. So then he spends time trying to figure out what his settings should be. After a process of maybe a whole morning, he finally has Git installed and hopes he is set up properly. And Richard only knows about Git and not any other tools that may have helped him with using Git. - -Bob has recently installed this tool called Chocolatey. He heads out to the community repository at [community.chocolatey.org](https://community.chocolatey.org/packages) and searches for Git. He learns that there are several cool tools for working with Git on Windows. He decides that he wants to use Git Extensions for helping him visualize some of the Git work. He opens a command line, types `choco install gitextensions` and hits Enter. Git Extensions has a dependency on Git for Windows, so Chocolatey downloads and installs it silently on his machine. It configures Git for proper Windows usage. Then Chocolatey downloads and silently installs Git Extensions on his machine. In less than ten minutes Bob is ready to go and has some of the best tools for working with Git available to him. - -Did Bob get lucky? No. It’s just that Bob didn’t have to really make that many decisions. He decided he wanted a tool. Then Chocolatey did all of the work, made all of the decisions, got the dependent applications, and even configured his machine properly. He has little left to do to finish setting up the machine for access to [GitHub](https://github.com). - -The moral of the story? Richard took 3-4 hours to get somewhat up to speed. Bob came fully up to speed in less than ten minutes. Don’t be a Richard. - -References - -* [https://lostechies.com/jimmybogard/2012/02/01/improving-the-git-windows-experience-downloads/](https://lostechies.com/jimmybogard/2012/02/01/improving-the-git-windows-experience-downloads/) diff --git a/input/en-us/chocolatey-vs-ninite.md b/input/en-us/chocolatey-vs-ninite.md deleted file mode 100644 index 49e8006240..0000000000 --- a/input/en-us/chocolatey-vs-ninite.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -Order: 73 -xref: chocolatey-vs-ninite -Title: Chocolatey vs Ninite -Description: A comparison between Chocolatey and Ninite -RedirectFrom: docs/chocolatey-vs-ninite -ShowInNavbar: false -ShowInSidebar: false ---- - -A lot of folks out there are always wanting to point out that there is Ninite when someone mentions Chocolatey. That is fine, Ninite works but it only has like 90+ things you can install. They are limited by what Ninite can rebundle and redistribute. Both are solid solutions in their own right, but you need to understand the needs and what the two solutions provide to really make a choice on them. - -## Package Management Approach - -### Ninite - -- Main purpose: Ninite is an installer that keeps off the crapware. -- Keeps everything centralized. -- Has a tight integration with products as the Ninite staff is the only one who updates packages. -- Guarantees success with installs since they control every aspect of the packages. -- Does not take contributions. -- All GUI based unless you pay for Pro version. -- Update apps simply by running the installer again. -- Only use case is for folks who have access to install applications on their machines. -- Only works with software installers. -- Closed source, but free. -- Paid options for CLI. - -### Chocolatey - -- Main purpose: Chocolatey is a global PowerShell execution engine that knows about a packaging format. -- Decentralized with a central community package repository. -- Multiple sources including private sources. -- Packages on [https://community.chocolatey.org/packages](https://community.chocolatey.org/packages) (the Chocolatey Community Package Repository) are created by the community and reviewed by moderators. -- Packages can embed software, use UNC paths or download software from another location (like the official distribution locations). -- Allows for community contributions. -- Allows for pay for apps to be included as packages. -- CLI focused, although there is a GUI (ChocolateyGUI). -- Easily scriptable which allows for adding setup scripts to things like source control. -- Update apps simply by running `cup packagename` or `choco upgrade all`. -- Integration with other package managers (Ruby Gems, Python PIP, WebPI, Windows Features, CygWin, etc). -- Able to be used without needing administrative permissions (portable packages are non-admin). -- Flexible, packages can work with native installers, set configuration, registry, do other tasks or any combination. -- Open source and free. -- Paid options [available](https://chocolatey.org/compare). - -#### Packaging solution needs (that brought about Chocolatey in the first place) - -- Good CLI that is simple to use -- A central repository that takes packages contributions from the community (and is being maintained) -- Ability to use additional/multiple sources -- Meta packages that can chain dependencies -- Virtual packages -- Packages should be easy to create / maintain -- Packages should be concise and be able to be created without worrying about distribution rights -- Unattended installs -- Installation of multiple packages with one command -- Script setup of environments -- A tool that enforces more security automatically - -## Chocolatey and Ninite : Compare and Contrast - -### Interfaces: - -- Ninite - choose apps from a website, download installer just for those apps. Pay for the pro version and use the command line. -- Chocolatey - open a command line. Install app with `choco install packagename `. Lather rinse repeat. - -### Packages: - -- Ninite - closed, only items available are what Ninite staff choose to make available. -- Chocolatey - community packages on a central server -- Chocolatey (internal use) - create packages on your own internal repository server - -### Package sources: - -- Ninite - one at Ninite.com -- Chocolatey - central community package repository at [https://community.chocolatey.org/packages](https://community.chocolatey.org/packages), create and use public/private sources (folder, network share, OData feed like nuget.org, [community.chocolatey.org] and/or myget.org). See [Host Your Own Server](xref:host-packages) for options. -- Chocolatey can also install from [alternative sources](xref:choco-command-install#alternative-sources) - choco install bash --source cygwin | choco install gemcutter --source ruby | choco install sphynx --source python | choco install IISExpress --source webpi - -### Creating packages: - -- Ninite - no -- Chocolatey - yes and quite simple. Run `choco new test` and look at the output - keep in mind that many times it takes complex tasks for managing software installation down to 1 PowerShell function call. Consider windirstat is: `Install-ChocolateyPackage 'windirstat' 'exe' '/S' 'https://windirstat.info/wds_current_setup.exe' -Checksum 123456 -ChecksumType 'sha256'` -- Chocolatey is building on technologies you may already know: - - PowerShell - take full advantage of PowerShell. - - Unattended installations / Silent installation -- Extend Chocolatey easily with PowerShell modules called [extension packages](xref:extensions). -- Use [Package Builder](xref:package-builder) to point Chocolatey to an installer and have it auto-detect and generate a full software deployment. -- Use [Package Internalizer](xref:recompile-packages) to internalize existing community packages quickly. - -### Available packages: - -- Ninite - Handled by Ninite staff, so there's less chance of anything being broken. -- Chocolatey (community repository) - Handled by the community, reviewed by moderators. Possibility of breakages unless using [licensed editions of Chocolatey](https://chocolatey.org/compare) due to [CDN Cache](xref:private-cdn). -- Chocolatey (internal repositories) - Handled by you, embedding software or using internal links you control. Zero chance of breakages that you don't control. - -### Package updates: - -- Ninite and Chocolatey community repository both can suffer from keeping packages up to date. -- Chocolatey (internal use) - good to go - -### Package dependencies: - -- Ninite - not really -- Chocolatey - Yes, dependencies are easy! Install Git Extensions, it makes sure Git is also installed. - -### Versioning/upgrades: - -- Ninite - sort of, you just rerun the installer every once in awhile -- Chocolatey - Yes. Consider `choco upgrade ` to upgrade a piece of software. Also consider `choco upgrade all`/`cup all` as a Windows Update for all of your 3rd party software. - -## Conclusion - -Chocolatey internal use is the best solution for an organization that has a low tolerance for breakages. There are no issues, you have a secure solution with complete control. You are building on top of technologies you know with a small amount of learning for packaging. Because it is PowerShell, you are not limited to just installers, and you can add additional logic before and after installations, and you are not limited to just "installing" software with packaging. - -Ninite is a solid solution if you don't mind not being able to script it and only install the applications that it has listed on the Ninite page. You are, however, possibly guaranteed that you have everything you need to install sheerly by having the Ninite Installer. In that way it may be better than using Chocolatey's community repository, which most packages require access to the internet to download installers that do not have distribution rights with them (Ninite may not incur this extra point of failure, but is quite limited in its offerings). Chocolatey community repository with [licensed editions of Chocolatey](https://chocolatey.org/compare) have almost no chance of breakages due to a [CDN Cache](xref:private-cdn) of those downloads. - -Chocolatey community repository has over 4,000 more packages than Ninite and a community that is driving to continually make it better. If you need to get to older versions of packages, many of the packages on the community repository allow for this. What Chocolatey community repository may lack in the possible guarantee that Ninite provides, it makes up for in features and options. Chocolatey can provide packages for non-free products, have multiple sources and folks can script the installations. Chocolatey is more than just an installer and with that does not require administrative privileges to use. - -Both Ninite and Chocolatey community repository solutions suffer from the issue of having the most up-to-date packages available, it's just that Chocolatey is more transparent about it. - -When it comes to internal use and creating and hosting your own (or internalizing existing) packages, nothing else holds a candle to Chocolatey. When you step up to [Chocolatey for Business](https://chocolatey.org/compare), you get access to features that allow an organization to really excel quickly. - -Whether you use Chocolatey or Ninite, consider that the two answer the same question differently and that is okay. They can live in harmony with each other and at some point Chocolatey may offer Ninite as package source. diff --git a/input/en-us/community-repository/api.md b/input/en-us/community-repository/api.md deleted file mode 100644 index b8a38730f8..0000000000 --- a/input/en-us/community-repository/api.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -Order: 20 -xref: ccr-api -Title: API Querying -Description: Information about querying the Chocolatey Community Repository API. ---- - -The Chocolatey Community Repository provides an API to allow package queries to be made, and results to be provided. -We hope to be able to answer your questions on what is supported and what is not supported, and on the acceptable ways that you can query the repository. - -## API Protocol - -> :choco-info: **NOTE** -> -> Chocolatey CLI and `chocolatey.lib` versions 1.x and earlier, used NuGet v2 OData Core libraries. - -The Chocolatey Community Repository uses the v2 OData protocol for queries, utilizing the NuGet v2 OData specification, where it is defined. Unfortunately, NuGet v2 OData specification is only loosely defined so one OData endpoint _may_ respond with different results to another, if it responds at all. - -Chocolatey CLI and `chocolatey.lib` use the NuGet v2 OData Client libraries to query, and process requests from, the Chocolatey Community Repository. - -## Supported API Query Tools - -We only support the following tools to query the Chocolatey Community Repository API: - -* [Chocolatey CLI](xref:choco) -* [`chocolatey.lib`](https://www.nuget.org/packages/chocolatey.lib) - -While you may create your own queries, and get results, this is not supported and may break in the future. Your own queries working today, are not guaranteed to work in the future. To guard against this happening, only use the supported methods above, to query the Chocolatey Community Repository. - -### Chocolatey CLI Machine Readable Output - -To get machine-readable output when querying the Chocolatey Community Repository using Chocolatey CLI, use the `--limit-output` command line option. See our documentation for more information on [scripting and best practices](xref:choco-commands#scripting-integration-best-practices-style-guide). - -For example, to search for all packages containing the word `kitty`: - -```powershell -PS> choco search kitty -Chocolatey v2.2.2 -kitty 0.76.1.13 [Approved] -kitty.portable 0.67.0 [Approved] -superputty 1.5.0 [Approved] -superputty.install 1.5.0 [Approved] -superputty.portable 1.5.0 [Approved] -5 packages found. -``` - -For the same query, but with machine-readable output: - -```powershell -PS> choco search kitty --limit-output -kitty|0.76.1.13 -kitty.portable|0.67.0 -superputty|1.5.0 -superputty.install|1.5.0 -superputty.portable|1.5.0 -``` - -You can easily parse the output to get a PowerShell object: - -```powershell -PS> choco search kitty --limit-output | ConvertFrom-CSV -Delimiter '|' -Header 'Name','Version' - -Name Version ----- ------- -kitty 0.76.1.13 -kitty.portable 0.67.0 -superputty 1.5.0 -superputty.install 1.5.0 -superputty.portable 1.5.0 -``` - -## Querying - -While we only support querying the Chocolatey Community Repository with [these tools](#supported-api-query-tools), there will be people who create their own queries. -We don't recommend this, but want to ensure if you are doing it, you do it safely. - -### Item Limit - -The total number of items returned from any query is limited to 10,000. This also affects paging. Attempting to retrieve item 10,001 will return an error of HTTP Status Code `406 - Not Acceptable`. - -Note that this affects both manual queries and queries made through Chocolatey CLI, Chocolatey GUI, and `chocolatey.lib`. - -This will be unlikely to affect the vast majority of users and will be limited to customers or community members who are retrieving a list of all packages, or paging through all packages, rather than searching for specific ones. If you have a legitimate need to regularly retrieve a full list of packages, please reach out to us on [Community Chat](https://ch0.co/community). - -### Using the `orderby` Parameter - -The following `orderby` parameters can be used to sort the results before they are returned: - -* `DownloadCount` -* `Published` -* `Id` -* `Title` -* `Version` - -If an unsupported `orderby` parameter is used, an HTTP Status Code `406 - Not Acceptable` response will be returned. - -An optional direction, `asc` for ascending, or `desc` for descending can be used with `orderby` parameters, for example `orderby=Version desc`. - -### Filtering - -Filtering should only be done using a [supported tool](#supported-api-query-tools) as there are too many filters and options to list here. - -And herein lies the problem. - -Because there are so many filters and options, an attempt is made to parse them and return results. -However, because of the complex nature of the queries, it may return an empty result, nothing or an HTTP Status Code `406 - Not Acceptable`. - -Any filter that is used more than once in the query, will return an HTTP Status Code `406 - Not Acceptable`. - -### `GetUpdates` Endpoint - -The `GetUpdates` endpoint is not supported and any call to it will return an HTTP Status code of `410 - Gone`. - -## Questions? - -If you are using a [supported tool](#supported-api-query-tools) and have questions about queries, please reach out to us on [Community Chat](https://ch0.co/community). diff --git a/input/en-us/community-repository/community-packages-disclaimer.md b/input/en-us/community-repository/community-packages-disclaimer.md deleted file mode 100644 index 8f057aa94f..0000000000 --- a/input/en-us/community-repository/community-packages-disclaimer.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -Order: 10 -xref: community-packages-disclaimer -Title: community.chocolatey.org Packages Disclaimer -Description: When you should, and shouldn't, use community.chocolatey.org -RedirectFrom: docs/community-packages-disclaimer ---- - -**Bottom line** - As an individual using Chocolatey, you are more likely okay if something breaks when setting up your personal machines - the Community Package Repository is typically fine for you. When it comes to using Chocolatey in an organizational context, you want reliability, control, and trust. You can gain trust over some packages on the community repository, and possibly some reliability if the binaries are included in the package. However there is a limiting factor with a public repository - distribution rights. This creates a large failure point that organizations just don't have when they are hosting their own internal packages. - -## Organizations - -### Summary - -As an organization, you want 100% reliability (or at least that potential), and you may want full trust and control as well. This is something you can get with internally hosted packages, and you are unlikely to achieve from use of the Community Package Repository. If your use of Chocolatey is for an organization/business, you likely have a low tolerance for production breakages and/or low trust for the greater internet. You likely would not want to give control of your infrastructure over to community members and volunteers. Organizational use of the community repository is not recommended. - -### Reliability - -Chocolatey is the best option for software management, as long as you are using package repository sources you can rely on. - -A huge thing in Windows ecosystem is copyright law and how it plays into distribution rights. Most software in POSIX-land (Linux) is open source friendly, which has friendly redistribitution rights (redist). So you can embed that software directly in the package and publicly offer it. In Windows that is not the case - an organization like Microsoft would get very upset if the Office 365 packages on the public Community Package Repository actually contained the Office 365 binaries. That creates an enormous failure point that is outside of the package's control when it needs to download files at install time (that dependency on internet-available files that are hoped to always be available, but in practice they are not). - -You can build a 100% reliable pipeline/workflow within the Chocolatey framework, just not with the community package repository. Building a reliable pipeline is huge. If you are a Windows admin wanting to trust a framework like Chocolatey, you are not going to use the Community Package Repository. Not when your reputation/job is on the line for picking the best options. - -> :choco-info: **NOTE** -> -> You can also achieve reliability when reusing community packages, as long as you [internalize](xref:recompile-packages) them. **Internalizing is not the same thing as caching the nupkg files like Artifactory, Cloudsmith, Nexus, ProGet, etc can do.** - -### Trust / Control -Windows admins typically need to do everything internally with no outside internet access. There is quite a bit more hush-hush, non-use of publicly available things without bringing it internal for absolute control and trust. There is a huge (semi-healthy, but maybe even unhealthy) lack of trust for anything reaching out to the internet. I'm not saying this is exclusive to Windows admins, but it is very much the norm. So using the community package repository is a non-starter for these kinds of folks. - -There are options for organizations to be able to reuse packaging from the community repository but make the package 100% offline and reliable. Please look at those options on the pricing page if you are interested. - -### Distro-provided Repositories - -There is another psychology aspect to this - Debian/RPM are nearly the ONLY way you install software on those machines, so it is expected that you would go that route. There are organizations using POSIX environments (typically RedHat) where it is becoming more typical that they pull those repositories local as well so they can trust everything will always work and be reliable. - -However Windows doesn't have a distro-provided repo. Chocolatey Software does not support use of the community repo for organizational use that doesn't also benefit the community (providing and maintaining packages). Reliability plays a huge part in that. If something breaks within the context of a package, then Chocolatey gets blamed (even though it is not Chocolatey's fault). - -## Excessive Use - -**Please note that individuals (even organizations) using the community repository are unlikely to hit excessive use numbers under normal usage scenarios.** - -> :choco-info: **NOTE** -> -> If you do find you have been blocked / rate-limited, having commercial licenses will not have any effect the policies with the community package repository. These policies were put into place to ensure stability and availability for the entire community, not to try to get folks to pay for licensing. - -See [rate limiting](#rate-limiting) below if you are seeing 429 errors (too many requests). - -Another aspect to keep in mind is that the community package repository is meant for the community. Perceived abuses of the community package repository that affect it in a detrimental way for the rest of the community will not be allowed. By abusive, it **may** mean more than **100 installs per hour on average over an internally determined amount of time** (it could be more, could be less) - this is not queries, this is **installs, upgrades** where actual package downloads are occurring. Let's say that is 30 days - that would mean 72,000+ package downloads over 30 days. When that is seen, our community team will make attempts to warn folks if we have known contacts (keep in mind it's highly unlikely we will have your contact information), and implement a temporary block to ensure your usage does not affect the community in a detrimental way. Many times this is due to a misconfiguration and can be corrected quickly. - -**Blocks are meant to be temporary bans, but require you to act to remedy the situation.** If you have been blocked, please see the next sections for corrective actions. - -> :choco-info: **NOTE** -> -> If you or your organization feels you will need to go over this limit with good reason and need whitelisted, please reach out at https://chocolatey.org/contact, choose "Blocked IP Address". As we have limited information, please include your name, email address, phone number, and the IP addresses you believe are blocked so we can contact you and verify if there is a ban. Once you have resolved any issues on your side, we can lift the ban. - -### How To Avoid Excessive Use - -To avoid excessive use, please see our [organizational deployment guide](xref:organizational-deployment-guide). Installation of Chocolatey itself and everything else should be from your internal repository and not directly from the community package repository. There are even ways to automate caching (see below) / [internalizing](xref:recompile-packages) (caching and internalizing are entirely different concepts) packages so you still get a pretty good hands off experience. - -If you are not able to take advantage of [internalizing](xref:recompile-packages) packages, you can still cache them locally (using package repository solutions like Artifactory, Cloudsmith, Nexus, ProGet, MyGet, etc), which will reduce your direct usage of the community repository. - -> :choco-info: **NOTE** -> -> Caching doesn't make the packages you are using from the community repository any more reliable, they may still need to download things from the internet at runtime - but it doesn't put you in a worse place than you already are at because you are already using the community repository directly which has issues identified in this document. If you want to achieve reliability when reusing community packages, you would need to [internalize packages](xref:recompile-packages). - -For caching of packages, something can be quickly implemented in 15-30 minutes to get your organization unblocked (and avoid rate limiting) while you look into implementing the rest of the [organizational deployment guide](xref:organizational-deployment-guide) (which takes about 1-2 hours). With 15-30 minutes, you can implement a [Proxy Repository](https://help.sonatype.com/repomanager3/.net-package-repositories-with-nuget) including the install of a [Nexus Repository Manager v3](https://community.chocolatey.org/packages/nexus-repository) (or [NXRM v2](https://community.chocolatey.org/packages/nexus-oss)) which automatically caches (but does not [internalize](xref:recompile-packages)) packages from the community repository (`https://community.chocolatey.org/api/v2`). This provides the same experience you get in using the community repository now but with more availability and no rate limiting! - -### What To Do When You Are Blocked For Excessive Use - -> :choco-info: **NOTE** -> -> A block will not automatically expire, you will need to contact our team to resolve the block. Rate Limiting on the other hand does automatically expire after one hour. Please see [rate limiting](#rate-limiting) below. - -If you have found that you have gone over the limit and have been warned/blocked, please reach out at https://chocolatey.org/contact (send message to "Blocked IP Address" in the drop down - you may need to do this from a different IP address) or go to our [Community Chat](https://ch0.co/community) to contact the community team. As we have limited information (only an IP address), please include your name, email address, phone number, and the IP addresses you believe are blocked so we can contact you and verify if there is a block. - -See the section above on avoiding excessive use - the expectation is that organizations would not use the community repository directly. As part of addressing any misconfigurations you might have, you will also need to see about addressing the previous section on "How To Avoid Excessive Use". - -Once you have resolved any issues on your side, we can lift the block. A block will be reimplemented later if we find excessive use again. - -### Rate Limiting - -> :choco-info: **NOTE** -> -> Purchasing licenses will not have any effect on rate limiting of the community package repository. Please read carefully below to understand why this was put in place and steps you can take to reduce issues if you run into it. HINT: It's not an attempt to get you to pay for commercial editions. - -As a measure to increase site stability and prevent excessive use, the Chocolatey website uses rate limiting on requests for the community repository. Rate limiting was introduced in November 2018. Most folks typically won't hit rate limits unless they are automatically tagged for excessive use. If you do trigger the rate limit, you will see a `(429) Too Many Requests`. When attempting to install Chocolatey you will see the following: - -![Exception calling "DownloadFile" with "2" arguments: The remote server returned an error: 429 Too Many Requests](/assets/images/cloudflare_ratelimiting_choco_install.png) - -It will look like the following using choco.exe: - -![The remote server returned an error: 429 Too Many Requests](/assets/images/cloudflare_ratelimiting_choco.png) - -If you go to a package page and attempt to use the download link in the left menu, you will see the following: - -![Error 1015, You are being rate limited](/assets/images/cloudflare_ratelimiting.png) - -You will start to see `429 Too Many Requests` if you have triggered the rate limit. Currently the rate limit will be in place for one hour. If you trigger it again, it will then be set for another hour. - -* Error 1015 - -> :choco-info: **NOTE** -> -> Please note that individuals using the community repository are unlikely to hit rate limiting under normal usage scenarios. - -**Details:** -* Installations/downloads of Chocolatey itself (chocolatey.nupkg) are rate limited at about 5 per minute per IP address - temporary ban expires after 1 hour. -* All other packages are rate limited at about 20 per minute per IP address - temporary ban expires after 1 hour. - - -> :choco-info: **NOTE** -> -> Rate Limiting defaults are subject to change with or without notice as we find a good happy medium that ensures ease of use and stability for our community. - -### What To Do When You Are Rate Limited - -> :choco-info: **NOTE** -> -> A rate limit will automatically expire after an hour, but if you hit the limit again, it will block for another hour. - -If you have found that you have been rate limited, please see [How To Avoid Excessive Use](#how-to-avoid-excessive-use). Implementing best practices for organizational use will limit chances of being rate limited again in the future. - -* Individual users being rate limited should reach out as per the next section and let us know as we are constantly adjusting limits to find a happy medium and need to have as much data to work with as possible. In addition to providing the requested information, make sure to also mention you are "individual use" and provide details on what caused the rate limiting. We may ask you to provide logs for further inspection. -* Organizational use will be asked to set up best practices for Chocolatey deployments. - -#### Special Requests on Rate Limiting - -If you have special needs and are being rate limited, please reach out to us as in special instances, we can whitelist your IP address for a small period of time. Do the following: - -> :choco-warning: **WARNING** -> -> Rate limits are temporary and expire within an hour, but will trigger again if you go over the limits. You may not need to file a special request if you can determine alternative means of use or if you [implement best practices](#how-to-avoid-excessive-use). - -* Go to https://chocolatey.org/contact. -* Select **Blocked IP Address** in "Send message to" drop down (this is important to get it routed to the right folks). -* :exclamation: **IMPORTANT**: Mention you are being rate limited, include your IP address. -* :exclamation:**IMPORTANT**: Note what special need your organization has in the message as well. -* You will typically receive a response somewhat quickly with options for you to implement. These are considered [best practices](#how-to-avoid-excessive-use) and can typically be implemented within 15-30 minutes. -* Our team will evaluate your request within a few business days and make a determination if your need qualifies for whitelisting. If so, the team will typically put in a temporary one time 7 day whitelist for you to [implement best practices](#how-to-avoid-excessive-use). - -> :choco-info: **NOTE** -> -> These are subjective, and special requests ONLY. Please ensure you [implement best practices](#how-to-avoid-excessive-use) so that you are not rate limited. - -See the section above on avoiding excessive use - the expectation is that organizations would not use the community repository directly. As part of addressing any misconfigurations you might have, you will also need to see about addressing the previous section on "How To Avoid Excessive Use". - -## Community Provided Packages Are Not Supported - -The packages contained at https://community.chocolatey.org/packages (the community repository) are collectively known as the Community Feed or Community Repository. Packages found on the community repository may not be supported by the original software vendor. If you have an issue with a package, contact the package maintainers through the community repository package page, Do not contact the software vendor directly. It bears repeating, DO NOT contact the software vendor directly. - -The packages you find on the community repository are completely unsupported. By using the packages on the community repository, you assume all risk for any issues or damages that may occur. The packages found in the community repository are built, moderated, and maintained by the community. While the packages are moderated by community moderators to help ensure safety and reliability (at the time of moderation), package maintainers and moderators assume no support nor liability for the packages. Neither package moderators nor package maintainers will be held liable for any issues, downtime, or damages that may occur from your use of the packages on the community feed. It is also not the responsibility of the package maintainers and/or package moderators to ensure that the package works in all scenarios. They are volunteers and thus are unable to support you and/or your business needs. - -Support is not guaranteed by package maintainers, but should you encounter issues, please work directly with the maintainers to get the package(s) corrected. Do NOT contact the software vendor directly. - -Transferring a package to another repository (even internal) with or without changes does not change the support level by the maintainers of Chocolatey, by the moderators nor maintainers, and not by Chocolatey Software, Inc. - -## Put It Another Way - -Due to software distribution rights, many of the packages contained on the community repository must download actual software from official distribution points, thus creating a dependency on those internet locations not changing (and from time to time they do, thus breaking a package until it is updated). This introduces a failure point for the community repository that is not found with internal packages. When hosting your own internal packages you would not be subject to software distribution rights, so you could embed the software directly in the package or pull from an internal share location, thus guaranteeing a reliable and repeatable software management process. - -For folks in the community that are not using Chocolatey for production purposes, with an understanding of the disclaimers set forth here, it is fine to use the community repository. For organizations that have a low tolerance for breakages and require a higher level of reliability, security, trust, and control, a self-hosted Chocolatey server is the recommended option. This guarantees that your installs, upgrades, and uninstalls will always work every time. This gives you complete control over what software gets installed. Also because you are vetting newer versions, you control when those newer versions are available for upgrade. Please see [Host Your Own Server](xref:host-packages) for more information. - - diff --git a/input/en-us/community-repository/faq.md b/input/en-us/community-repository/faq.md deleted file mode 100644 index 585a6f40f5..0000000000 --- a/input/en-us/community-repository/faq.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -Order: 90 -xref: ccr-faq -Title: Chocolatey Community Repository FAQ -Description: Chocolatey Community Repository Frequently Asked Questions ---- - -### How Do I Ask Questions About a Package? - -If you have a question about the _package_, please follow **both** these steps: - -1. [Contact the package Maintainers](#how-do-i-contact-the-package-maintainers). Some Maintainers have opted-out of receiving email, so this option may not be available. -1. [Find the package source](#how-do-i-find-the-package-source) and if the repository supports it, raise a discussion. The majority of Maintainers have the package source on a platform such as GitHub which allows issues and discussions to be created, if enabled. - -![Package Source link on the Chocolatey Community Repository package page](/assets/images/triage-packagesource.jpg) - -### How Do I Ask Questions About the Package Software? - -If you have questions about the _software_ the package installs, please contact the Software Vendor/Author. Maintainers do not provide support for the software that is packaged. - -If you want to ask questions about the _package_, see [here](#how-do-i-ask-questions-about-a-package). - -### How Do I Contact the Package Maintainers? - -You may want to contact the package maintainers with package questions, or to report a broken or outdated package. On the [Chocolatey Community Repository](https://community.chocolatey.org/packages) package page, click the **Contact Maintainers** link. - -![Contact Maintainers link on the Chocolatey Community Repository package page](/assets/images/triage-maintainers.jpg) - -If your question is about the software installed by the package, please contact the Software Vendor or Author directly as package maintainers cannot provide software support. The exception is if the package Maintainer is also the Software Vendor/Author. You can find out who the package maintainers are on the [Chocolatey Community Repository](https://community.chocolatey.org/packages) package page. - -![Package Maintainers profile links on the Chocolatey Community Repository](/assets/images/triage-maintainerlinks.jpg) - -### How Do I Contact the Site Admins? - -You should contact the Site Admins if: - -* You have read this FAQ and your question is not answered. - -You should not contact the Site Admins to: - -* [Request a package be updated](xref:package-triage-process#package-is-outdated). -* [Report a package is outdated](xref:package-triage-process#package-is-outdated). -* Marketing or sales communications. -* [Ask for package support](#how-do-i-ask-questions-about-a-package). -* [Ask for support on the packaged software](#how-do-i-ask-questions-about-the-package-software). -* [Ask for Chocolatey product support](https://chocolatey.org/support). - -To contact the Site Admins, click the **Contact Site Admins** link to contact the site Administrators. Please include as much information as possible including dates and times. The Site Administrators will then follow up with you. - -![Contact Site Admins link on the Chocolatey Community Repository package page](/assets/images/triage-siteadmins.jpg) - -### How Do I Create Chocolatey Packages? - -It's easy to [create and maintain packages](xref:create-packages). - -### How Do I Find the Package Source? - -On the [Chocolatey Community Repository](https://community.chocolatey.org/packages) package page, click the **Package Source** link, if it's available. - -![Package Source link on the Chocolatey Community Repository](/assets/images/triage-packagesource.jpg) - -Not all Maintainers provide a publicly accessible package source. If the **Package Source** link is missing, you also could try to find a link to the package sources in the profiles of the Maintainers. - -![Package Maintainers profile links on the Chocolatey Community Repository](/assets/images/triage-maintainerlinks.jpg) -![Package Maintainer profile on the Chocolatey Community Repository with GitHub repository link](/assets/images/triage-maintainerrepository.jpg) - -### How Do I Inspect the Contents of a Chocolatey Package? - -> :choco-info: **NOTE** -> -> Packages submitted before 2014 do not have files listed under the **Files** section. - -The contents of every Chocolatey package is available to be inspected both on the Chocolatey Community Repository package page under the **Files** section. - -![Chocolatey Community Repository package files section with chocolateyInstall.ps1 PowerShell script expanded](/assets/images/moderation-10.jpg) - -You can also download the actual package and inspect the contents. On the left menu there is a **Download** button where you can download and rename the `.nupkg` file extension to `.zip`, extract it and see the contents. - -![Download package button on the Chocolatey Community Repository](/assets/images/triage-download.jpg) - -### How Do I See All Versions Of a Package - -Packages can have multiple version, both stable and prerelease. All of these versions are listed on the package page and can be found by scrolling down the page to the **Version History** section and clicking the link. - -![Version History section of the package page on the Chocolatey Community Repository](/assets/images/packagepage-versionhistory.jpg) - -Only a limited number are shown initially. If there are more version available, click the **Show Additional Versions** button to view them all. - -### How Do I See the Package Source Code? - -See [this FAQ question](#how-do-i-find-the-package-source). - -### How To Report An Abusive Package - -> :choco-info: **NOTE** -> -> Do not use the **Report Abuse** form to submit reports of: -> -> * [A package being outdated](xref:package-triage-process#package-is-outdated). -> * [A package being broken or not working](xref:package-triage-process#package-is-broken). -> * Marketing or sales communications. -> * [Package support](#how-do-i-ask-questions-about-a-package). -> * [Support on the packaged software](#how-do-i-ask-questions-about-the-package-software). -> * [Chocolatey product support or help](https://chocolatey.org/support). - -We take package abuse very seriously. But what is package abuse, or an abusive package? - -There are many definitions of what could make a package, or the software it installs, abusive. An abusive package could be: - -* A package that installs software that contains malware, adware, or potentially unwanted applications (PUA). -* A package that violates [distribution rights](xref:legal#distributions). - -If a package is abusive, please report it by clicking on the **Report Abuse** link on the package page, fill out and submit the form. The Site Administrators will follow up with you. - -![How to report abuse on the Chocolatey Community Repository](/assets/images/triage-reportabuse.jpg) - -### Why do I get a 500 Internal Server Error when trying to push my package? - -If you receive a `500 Internal Server Error` when pushing a package, you may have a malformed package that the server was unable to process. -One such case is documented in a [GitHub issue](https://github.com/chocolatey/home/issues/303). - -Make sure that none of the `` entries in the `nuspec` file of your package have name collisions with other files or folders being packed. -This is usually rare but can be encountered more commonly if you are trying to pack files which don't have a file extension. -For example, if you have `` entries that may look like this, you will need to change the name of the file or folder in the package to avoid collision: - -```xml - - -``` - -There are two possible solutions for this particular case: - -```xml - - - - - - - -``` - -See an [issue we raised on the NuGet repository](https://github.com/NuGet/Home/issues/13273) for more information on the NuGet bug which can cause this kind of malformed package. - -If you receive a `500: Internal Server Error` that is not related to this specific case, please [file an issue on GitHub](https://github.com/chocolatey/home) so we can investigate the issue. diff --git a/input/en-us/community-repository/index.md b/input/en-us/community-repository/index.md deleted file mode 100644 index ebc5e3601e..0000000000 --- a/input/en-us/community-repository/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 80 -xref: chocolatey-community-repository -Title: Chocolatey Community Repository (CCR) -Description: This is the default location where Chocolatey will install packages from ---- \ No newline at end of file diff --git a/input/en-us/community-repository/maintainers/deprecate-a-chocolatey-package.md b/input/en-us/community-repository/maintainers/deprecate-a-chocolatey-package.md deleted file mode 100644 index 30465a8c91..0000000000 --- a/input/en-us/community-repository/maintainers/deprecate-a-chocolatey-package.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -Order: 30 -xref: deprecate-a-package -Title: Deprecate a Package -Description: How to deprecate a Chocolatey package -RedirectFrom: - - docs/how-to-deprecate-a-chocolatey-package ---- - -## The Problem -From time to time, a previously approved Chocolatey Package needs to be deprecated. This could be for a number of reasons: - -* It was created in error. -* It has been superseded by another package. -* It is an older package that no longer follows the [Package Guidelines](xref:create-packages). -* Its package id has been changed to something that better fits with the [package naming guidelines](xref:create-packages#naming-your-package). - -All versions of this package could simply be [unlisted](xref:list-unlist-a-package) from chocolatey.org, meaning that they could no longer be installed, however, this solution is not ideal. Any user who previously installed this package, and added it as part of an installation script, would get an error the next time that they tried to install it, and this is far from ideal. - -When a package needs to be deprecated, it needs to be handled in such a way that existing users will continue to be able to use the old package id, but take advantage of the replacement package, if there is one. - -## The Solution -When deprecating a Chocolatey Package, the following steps should be followed: - -* Create a **[new version](xref:create-packages#package-fix-version-notation)** of the deprecated Chocolatey Package. -* Prepend **[Deprecated]** to the **title** of the package (e.g. `[Deprecated] Software Title` -* Update the package **description**: Why is the package being deprecated? -* Add a **[dependency](http://docs.nuget.org/docs/reference/nuspec-reference#Specifying_Dependencies) on the other package** (if the package is being superseded). -* **Remove all files** except the `.nuspec` from the Chocolatey Package. -* Replace `...` section in `.nuspec` with `` tag to prevent any file from being included with the package. -* **Remove the iconUrl**. -* **[Unlist all versions](xref:list-unlist-a-package)** from the package gallery, **except** the final deprecated version. The final deprecated version is required so that there is an update path to the new package. - -By following this process, any existing users who try to update the old package will automatically get the new package, as it will be installed as a dependency. diff --git a/input/en-us/community-repository/maintainers/index.md b/input/en-us/community-repository/maintainers/index.md deleted file mode 100644 index b236ba8d44..0000000000 --- a/input/en-us/community-repository/maintainers/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 40 -xref: maintainers -Title: Maintainers -Description: Information for maintainers of packages on the Chocolatey Community Repository ---- \ No newline at end of file diff --git a/input/en-us/community-repository/maintainers/list-unlist-a-chocolatey-package.md b/input/en-us/community-repository/maintainers/list-unlist-a-chocolatey-package.md deleted file mode 100644 index 89db81896b..0000000000 --- a/input/en-us/community-repository/maintainers/list-unlist-a-chocolatey-package.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -Order: 30 -xref: list-unlist-a-package -Title: List / Unlist a Package -Description: How to list or unlist a Chocolatey package ---- - -## The Problem - -From time to time, the visibility of a previously approved Chocolatey package version needs to be changed. This could be for a number of reasons, for example: - -* The package version was uploaded in error. -* The installer or embedded files are no longer available. - -Leaving a package as listed could mean that any user who tries to install or upgrade this package might get an error, and this is far from ideal. - -## The Solution - -You can change the visibility of an individual Chocolatey package version by following these steps: - -1. Navigate to the package page, scroll down, and expand, **Version History**. If a package is listed, and visible on the Chocolatey Community Repository it will say **yes**. If a package is unlisted, it will say **no**. - -1. Under the **Listed** column, click **yes** next to the version you want to unlist, or **no** next to the version you want to list. - - ![Example of a package visibility on the Chocolatey Community Repository](/assets/images/maintainers/unlist-package-status-listed.png) - -1. To unlist the package version, untick the box next to **List..**. To list the package version, ensure the box is ticked. Click **Save Changes** to update the package visibility. - - ![Example of unlisted a package from the Chocolatey Community Repository](/assets/images/maintainers/unlist-package.png) - -1. Check the visibility of the package has been updated by expanding **Version History** again. - - ![Example of unlisted a package from the Chocolatey Community Repository](/assets/images/maintainers/unlist-package-status-unlisted.png) - -## FAQ - -### Can I list or unlist all versions of a package at once? - -At this time you cannot list or unlist all versions of a package at once. You must list or unlist individual package versions. diff --git a/input/en-us/community-repository/maintainers/package-maintainer-handover.md b/input/en-us/community-repository/maintainers/package-maintainer-handover.md deleted file mode 100644 index 94d8e29b71..0000000000 --- a/input/en-us/community-repository/maintainers/package-maintainer-handover.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -Order: 20 -xref: package-maintainer-handover -Title: Take Over Package Maintenance Exclusively -Description: Package maintainer handover -RedirectFrom: docs/package-maintainer-handover ---- - -# Package Maintainer Handover - -> :choco-info: **NOTE** -> -> This process comes after the [Package Triage Process](xref:package-triage-process). If you are a **software vendor** wanting to maintain your own software's packages, please see [maintain packages for my software](xref:package-triage-process#i-want-to-take-overhelp-with-package-maintenance-for-my-software). - - -When a package maintainer is deemed no longer maintaining a package, a new maintainer or maintainers can assist and/or takeover. This is done through the [Package Triage Process](xref:package-triage-process). - -Once an admin makes you a maintainer you will need to click on the link in your email to confirm. - -Once that is done you have several steps: - -* Obtain the source for the package. Look at the packageSourceUrl to see if it is filled out or not. - - ![Package source link](/assets/images/maintainer-handover/package-source-link.png) - -* Look for the maintainer's profile to see if they have a GitHub repository for their packages. - - ![maintainer profile with github repository link](/assets/images/maintainer-handover/github-repository-link.png) - -* If you don't find it there, attempt to find it on GitHub with some google-fu. -* If all else fails, download the package from the website (use the Download link on the left side). -* Use unzip to unpack the package and remove the files that are only used in packaging. -* Put that in your GitHub repository for packages. -* Ensure you have a link to that repository in your Chocolatey profile. -* Commit the package as is prior to any changes. If you are moving it over from another repository, just copy the current files/folders related to that package into your repository. -* Now make your changes/fixes/updates. Commit those changes as necessary. -* One thing to update is any links to the old repository such as images and/or maintainers. -* Also add/update `` to point to your repository. -* Build the package and test locally. -* Push the package with the updates/fixes. -* If brought in from another repository, be sure to send a Pull Request to that repository to have the package removed from there (or at the very least file an issue). Link the new location in that request for others who might be searching. diff --git a/input/en-us/community-repository/moderation/index.md b/input/en-us/community-repository/moderation/index.md deleted file mode 100644 index a1fed5276b..0000000000 --- a/input/en-us/community-repository/moderation/index.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -Order: 50 -xref: moderation -Title: Moderation -Description: Information about the package moderation used on the Chocolatey Community Repository -RedirectFrom: docs/moderation ---- - -The community feed, which is found at https://community.chocolatey.org/packages, is a moderated feed. That means all new versions of packages are human reviewed prior to approval to check for safety, quality, and correctness. See [What is moderation](xref:faqs#what-is-moderation) for more details. There are also [trusted packages](xref:faqs#what-is-a-trusted-package), which only go through automated moderation review and bypass human review as they are coming from trusted sources and/or the software vendors themselves. - -By safety - we check that the package scripts do not do anything devious and that you get the software that the package indicates you are getting. Please note that the underlying software may contain crapware/malware (although it is usually not installed when allowing Chocolatey to install silently). This is not checked for currently, but we have plans for checking this in licensed versions of Chocolatey because a feature doing that is not free for us to provide. - -## Definitions - -* package - The Chocolatey/NuGet package -* software - The underlying software that the package assists in installing -* installer - The native installer, usually packaged as MSI, NSIS, InstallShield, Wise, Squirrel, or some other flavor. -* the validator - The [package validation service](xref:package-validator) checks the quality of a package based on requirements, guidelines and suggestions for creating packages for Chocolatey’s community feed. We like to think of the validator as unit testing. It is validating that everything is as it should be and meets the minimum requirements for a package on the community feed. -* the verifier - The [package verifier service](xref:package-verifier-service) checks the correctness (that the package actually works), that it installs and uninstalls correctly, has the right dependencies to ensure it is installed properly and can be installed silently. The verifier runs against both submitted packages and existing packages (checking every two weeks that a package can still install and sending notice when it fails). We like to think of the verifier as integration testing. It’s testing all the parts and ensuring everything is good. - -## Requirements and Guidelines - -While probably the most comprehensive, this list may not be fully up-to-date. This should serve as a most general understanding, knowing that the [validator](xref:package-validator) may be checking for newer things than are written here and that reviewers/moderators may find newer things to check from time to time. - -> :choco-info: **NOTE** -> -> Moderators tend to get somewhat picky about properly stating the license, authors (software vendors), and copyright attributions. They are very important to protect both maintainers and the software vendors. - -> :choco-info: **NOTE** -> -> This is still written based on a reviewer reading it, this will get cleaned up more over time to better explain it from a non-reviewer perspective. - -### Existing Packages - -This section provides the requirements for packages that have had at least one released version approved or exempted. This includes any packages that existed prior to moderation being turned on (possibly an Unknown status). - -#### Requirements - -Requirements represent the minimum quality of a package that is acceptable. When a package version has failed requirements, the package version requires fixing and/or response by the maintainer. Provided a Requirement has flagged correctly, it **must** be fixed before the package version can be approved. The exact same version should be uploaded during moderation review. - -* ProjectUrl - it's required for the community feed -* The authors field (software author/vendor) is not being used for the maintainers field (exception: when the maintainer is also the author) -* The copyright is used appropriately. Look at anything you can find that states the copyright. -* If there is a license available, it **must** be included in the licenseUrl. -* Is the title appropriate? -* At least something written in the description. It should be sufficient to explain the software. -* The description should explicitly mention if this package installs trial software or software that needs a license present, or both. -* The tags field is not being abused - note this doesn't mean they are missing tags you believe they should have (that is a guideline). -* Tags do not include "chocolatey" (with the exception of the chocolatey packages) -* When using an `iconUrl`, GitHub raw links are not allowed; linking through a CDN like jsDelivr, Statically, or Githack is required. -* When using an `iconUrl`, the icon needs to be hosted at a location that the package maintainer has control over. In most cases this is the package source repository, but can be the software website if the software author is also the package maintainer. -* Look over the package files - * If binaries are included in the package, does the maintainer have distribution rights? If they have explicit permission, a copy of that in PDF should be in the package contents. - * **Install/Uninstall scripts:** - * Do the scripts try to do anything malicious? This is almost always immediate grounds for banning the maintainer and deleting their packages. - * Do the scripts set good defaults for silent args? - * Is there anything there that would not work with POSH v2? - * If it is a download, is it getting it from the proper location? Use the project site (projectUrl) to determine where the download for the file is coming from and it should match the one in the package files. If not there needs to be a really, really good reason for not doing so. - * Does the download version match the package version? - * Does the download include both x86 and x64 urls if available? - * Flag the use of any of the following: $nugetChocolateyPath, $nugetPath,$nugetExePath, $nugetLibPath, $chocInstallVariableName, $nugetExe - * Does the PowerShell script try to use any choco commands? e.g. choco install/upgrade/uninstall? - * Does the package try to do anything that an existing Chocolatey function already covers? The maintainers would need a really good reason for diverging from that. - * If the package is a portable package (downloads a zip file or non-install archive, many times carries the .portable name), does it try to put that in Program Files? This is a no no because Program Files requires admin permissions to write to and is typically the place for natively installed software. -* Does the package install correctly? -* Does the package uninstall correctly? (this means the package, not the underlying software. We'd like to have that as well but it's more a guideline at the moment than a requirement. Patience, we will get there). -* Brand New Packages **ONLY** (no approved or existing version in history, prereleases do not count) - * Package Id naming - if the naming doesn't follow our conventions, it is grounds for rejecting immediately with the suggestion they resubmit with suggested name. Note that they may have had prereleases already, and it's still okay to move forward with the rejected status as long as the name of the name of package hasn't been previously approved. See [Naming your package](xref:create-packages#naming-your-package) - * suggest the id split if over 25 chars with no "-" in the id - * flag on "." in name (unless .portable/.install) - -#### Guidelines - -Guidelines are strong suggestions that improve the quality of a package version. These are considered something to fix for next time to increase the quality of the package. Over time Guidelines can become Requirements. A package version can be approved without addressing Guideline comments but will reduce the quality of the package. - -* Trial software should include the #trial tag. (will become a requirement in Feb 2016) -* Software that requires a license should include a tag #license. (will become a requirement in Feb 2016) -* LicenseUrl is nearly a requirement. The only reason it sits in guidelines is that not all software has a url out there containing its license information. We request that in those cases they point to the url for the FOSS license of the software, if they have an open license. -* Usage of the `iconUrl` is very strongly encouraged, however, the addition of a `iconUrl` is a guideline and something to note for a maintainer to fix up next time. Some software doesn't have a proper icon, in which case an `iconUrl` should not be added. See the requirements section for the requirements if a `iconUrl` is included. -* Suggest description get really filled out and they take full advantage of the use of markdown. -* Summary is important, but it doesn't show up on the package page. -* Tags could always use suggestions to add. -* Look over the package files - * **Install / Uninstall Scripts:** - * Be familiar with things that have been deprecated and add a gentle reminder about those things for them to clean up. - * Are the commented lines from the template in there? Those should be cleaned up. It is not required to remove all comments, some comments are helpful. It’s a bit subjective on what is helpful and what is noise. -* Something in the releaseNotes section would be great. - -## Package Review Process - -When reviewing new and existing packages, a reviewer/moderator will have a few things left for review after the verifier and validator have verified a package. - -### Moderation Workflow - -#### First Time Go Workflow - -When a good package is submitted, the normal flow of moderation works roughly like this: - -1. A maintainer submits a package. That puts the package in a "Pending" status (Pending automated review checks). -1. If automated reviews don't require changes, the package moves to a "Ready" status. (Ready for Reviewer) -1. If a moderator doesn't find any required changes, they move the package to an "Approved" status. - -#### Full Workflow - -The full normal workflow is like this: - -1. A maintainer submits a package. That puts the package in a "Pending" status (Pending automated review checks). -1. If automated reviews don't require changes, the package moves to a "Ready" status. (Ready for Reviewer) -1. If any of the automated review checks flag a package, the package moves to a "Waiting" status. (Waiting for maintainer to take corrective action) -1. The package will sit in the Waiting status until a maintainer resubmits the package (starts the process from step one) or responds ("Responded"). Responses are typically questions, comments or requests for exempting from the verifier. (Maintainer responded, waiting for review/Maintainer update) -1. If the package is in "Responded", it moves up the queue and waits for a reviewer to go over the response and process it accordingly. -1. If a package is resubmitted, it doesn't go into a Ready status. It moves to an "Updated" status at the top of the queue. (Maintainer updated, waiting for reviewer) -1. If a moderator asks for required changes, the package moves to a "Waiting" status. (back to step 4) -1. If a moderator doesn't find any required changes, they move the package to an "Approved" status. - -#### Trusted Package Workflow - -This is the trusted package workflow: - -1. A maintainer submits a trusted package. That puts the package in a "Pending" status (Pending automated review checks). -1. If automated reviews don't require changes, the package moves to an "Approved" status. -1. If any of the automated review checks flag a package, the package moves to a "Waiting" status. (Waiting for maintainer to take corrective action) -1. The package will sit in the Waiting status until a maintainer resubmits the package (starts the process from step one) or responds ("Responded"). Responses are typically questions, comments or requests for exempting from the verifier. (Maintainer responded, waiting for review/Maintainer update) -1. If the package is in "Responded", it moves up the queue and waits for a reviewer to go over the response and process it accordingly. -1. If a package is resubmitted, it doesn't go into a Ready status. It moves to an "Updated" status at the top of the queue. (Maintainer updated, waiting for reviewer) -1. If the package passes automated review, the package moves to an "Approved" status. -1. If a moderator asks for required changes, the package moves to a "Waiting" status. (back to step 4) -1. If a moderator must manually override the approval, they move the package to an "Approved" status. - -### Maintainer Process - -**FYI:** Ensure that you can receive emails from Chocolatey.org so that you will receive email notifications when a package review is updated. - -The process of moderation review is an interactive process for both maintainers and moderators. As a maintainer you submit packages and they are reviewed to be sure they meet a minimum quality and correctness to be published on Chocolatey.org. It's an important distinction that while almost all valid packages are approved, a package can be rejected for a variety of reasons. - -Packages go through three automated checks: validation, verification, and cleanup. There is about a 30 minute lag time from submission until automatic review kicks off - this allows the CDN to recheck and pull a newer version of the package up (in the case of resubmission), so that the package version being verified is the one you submitted and not a stale copy. - -When you receive emails that require you to take action, you should review what is requested and make the changes. If a package is flagged and needs changes based on requirements, the process is for you to make the required changes and resubmit the **exact** same version. The faster you respond to the review process, the faster your package can get approved. - -The cleanup automated check, aka the cleaner, checks packages that have been in a 'waiting' (waiting for maintainer to take action) status with no action/response within 20 days and follows up with a final reminder. If after 15 more days nothing has been done, the package will automatically be rejected on non-response. We feel that 35 days prior to automatic close is ample time for a maintainer to move the ball forward (even one going on holiday). If a package gets rejected, it doesn't mean that we don't value your contributions, just that we can not continue to hold packages versions in a waiting status that have possibly been abandoned. The rejected status is also reversible in case a maintainer wants to pick it back up within a year. - -Moderators give you the benefit of the doubt and will work with you to help you get a package to an approved status. (This also includes the older review process based on email before the site allowed you to comment). - -### Reviewer / Moderator Process - -Typically a package goes into the moderation queue when submitted.You can get to that by signing in and going to the packages page like you normally would. - -1. You should see a new drop down near the top that allows you to change your view. This is the moderation queue. - - ![Moderation Queue Dropdown](/assets/images/moderation-1.jpg) - -1. You will see items arranged in order based on reviewed and resubmitted at the top, items ready for review in order based on when they were submitted, and at the end of the queue, you will see items that are waiting for maintainer response. - - ![Moderation Queue](/assets/images/moderation/moderation-queue.png) - -1. You grab a package and head in and review it based on the following items in the requirements and guidelines. -1. Ensure package tests have ran. It will have both comments in the review and a colored ball up next to the title of the package. A package status box is present at the top of each package page with test results. The left side of the ball next to the package title represents verification testing, while the right side represents validation testing (see image below). Color of ball sections indicate: - - **Green** if it is ready for review and approval. - - **Yellow** if still pending verification/validation (has not yet run). - - **Red** if it failed verification/validation. The maintainer needs to fix or respond. If you find a package needs to skip verification, please contact an admin to do so. If you see a network issue from the log, you can rerun verification (see how in the next step). - - **Grey** if a package skips verification/validation for some reason (which will be listed by the admin that flagged the package to skip testing). If possible, you will need to run the install/uninstall yourself. - - ![Package Testing Results](/assets/images/moderation-4.jpg) - -1. Check over the verifier logs to be sure everything looks good (follow the link from the button). If necessary, you can rerun the verifier. - - ![Rerun](/assets/images/moderation-5.jpg) - -1. Go over the review log - shows history and review information so far. Note that when the validator runs it leaves comments. Look for it to have done the automated part of the requirements/guidelines checks. If it has not, you are responsible to check all [requirements/guidelines](#requirements-and-guidelines) (see [Requirements and Guidelines](#requirements-and-guidelines) above). - - ![Review Notes](/assets/images/moderation-6.jpg) - -1. Look at the notes section from the latest run of the validator to see if there are additional flagging follow ups from the validator. -1. Check over the package based on [moderator review](#moderator-review) (below). -1. Review the previous comments if there are any. - - ![Review previous comments for other package versions](/assets/images/moderation/moderation-previous-comments.png) - -1. Look through the package files - - ![Package Files](/assets/images/moderation-10.jpg) - -1. Leave comments in the review box ("Add to Review Comments" section) if you have any. Note that you can use markdown here. - - ![Review box](/assets/images/moderation-11.jpg) - -1. If you are approving the package, change Package Status to Approved. If you are Rejecting a package, change the status to Rejected. Otherwise leave the status as is (likely in Submitted). -1. If you are making a comment or doing another action, but don't want to flag/hold the package for the maintainer to take action, uncheck the "require maintainer to make changes?" box. This is not required to be unchecked if you are approving the package. - - ![Require maintainers to make changes?](/assets/images/moderation-13.jpg) - -1. If you are doing an action that doesn't need to notify the maintainer, uncheck "Send Maintainer email?". -1. Click Save. You should get a message that the message was sent successfully. -1. The maintainers receive an email noting the comments. They will follow up on the package page with their comments. -1. Once the package is updated, it will show up in the top of the queue. At that time, please review it and make sure the maintainers made all changes requested. - -#### Moderator Review - -You can only ever require a maintainer to make changes if there are findings from the requirements section. Guidelines are strong suggestions that will improve the quality of the package, but consider that a quality over time. A maintainer is NOT required to make changes based on guidelines/suggestions. This deserves to be said twice: **"A moderator cannot hold up a package based on guidelines/suggestions *alone*"**. - -The validator checks quite a few items ([validator rules](xref:package-validator)) and leaves a few for you to check. Ensure you have looked over the notes that it has left. - -With the exception of included binaries, a review that doesn't flag should take under a minute. If you are holding a package, you can refer the maintainer to this link to save time: https://docs.chocolatey.org/en-us/community-repository/moderation - -##### Requirements - -Always be explicit that you are waiting on the maintainer to fix and resubmit the same version of the package so you can move the review process along. - -* Is the title appropriate? -* The description should explicitly mention if this package installs trial software or software that needs a license present, or both. -* The authors field (software author) is not being used for the maintainers field (exception: when the maintainer is also the author) -* The tags field is not being abused - note this doesn't mean they are missing tags you believe they should have (that is a guideline). -* Binaries - * If binaries are included in the package, does the maintainer have distribution rights? If they require explicit permission, a copy of that in PDF form should be in the package contents. - * Find the checksum of the official binaries and verify they match the included binaries (listed on the package page). -* Automation scripts (the `ps1`/`psm1` files such as `chocolateyInstall.ps1`) - * Do the scripts try to do anything malicious? This is almost always immediate grounds for banning the maintainer and deleting their packages. - * Do the scripts set good defaults for silent args? A package should almost ALWAYS install completely silently by default. If a maintainer makes the argument that it is so folks can choose what to pass, remind them this already exists through install arguments (CommandsInstall#options-and-switches) and if they want to add package parameters (How-To-Parse-PackageParameters-Argument), they can also do that (and add them to the description). - * Is there anything in the scripts that would not work with POSH v2? (We are working on making this automatically checked by the validator - see https://github.com/chocolatey/home/issues/34) - * If the package downloads anything, is it getting downloads from the proper location? Follow the projectUrl to the project site to see where it is downloading from - it should match the scripts. If not there needs to be a really, really good reason for not doing so. - * Does the download version match the package version? - * Does the download include both x86 and x64 urls if available? -* Not a package duplicating another existing package -* Brand New Packages **ONLY** (no approved or existing version in history, prereleases do not count) - * Package Id naming - if the naming doesn't follow our conventions, it is grounds for rejecting immediately with the suggestion they resubmit with suggested name. Note that they may have had prereleases already, and it's still okay to move forward with the rejected status as long as the name of the name of package hasn't been previously approved. See [Naming your package](xref:create-packages#naming-your-package) - * suggest the id split if over 25 chars with no "-" in the id - * flag on "." in name (unless .portable/.install) - -##### Guidelines - -If a package is only flagging on guidelines, be sure to move forward on approval (this means no requirements flagged by you or the validator checks). - -* Trial software should include the #trial tag. (will become a requirement in Feb 2016) -* Software that requires a license should include a tag #license. (will become a requirement in Feb 2016) -* Tags could always use suggestions to add. -* Automation scripts (the `ps1`/`psm1` files such as `chocolateyInstall.ps1`) - * Do any scripts try to do anything that an existing Chocolatey function already covers? The maintainers would need a really good reason for diverging from that. - -## Roles - -* Maintainer - A person that maintains packages. Maintainers are usually subject to the review process. -* Reviewer - Able to review packages but not approve/reject them -* Moderator - Able to set/remove package maintainers, review packages, approve/reject them, able to unlist packages. -* Administrator - Has access to administrative sections of the site. Can perform all functions that a moderator can perform. - -#### Becoming a Maintainer - -To become a package maintainer, you must have an account on https://community.chocolatey.org and have at least one package on the site. - -#### Becoming a Reviewer - -TBD - -#### Becoming a Moderator - -There is no set process for becoming a moderator yet. Usually it is having many approved packages and understanding the process of creating Chocolatey packages. Eventually it will be something you earn through your reputation on the site. - -* Make awesome packages -* Work on the Disqus threads and mailing list. -* Have a desire to better the quality of Chocolatey -* Know a little PowerShell. More is better but yeah. -* Be friendly and customer service-oriented - -#### Becoming an Admin - -This is not an achievable status. - -### New Reviewers / Moderators - -* Understand the package creation process and the current recommendations, written at [create packages](xref:create-packages). -* Become familiar with the package guidelines and all of the different Chocolatey functions available. [Helper reference](xref:powershell-reference) -* Join the [chocolatey-moderators at google groups dot com](https://groups.google.com/forum/#!forum/chocolatey-moderators) mailing list. This is necessary for communication with other moderators and receiving messages regarding changes in moderation. -* Join our [Community Chat](https://ch0.co/community) and hang out. diff --git a/input/en-us/community-repository/moderation/package-cacher.md b/input/en-us/community-repository/moderation/package-cacher.md deleted file mode 100644 index e36b402d9a..0000000000 --- a/input/en-us/community-repository/moderation/package-cacher.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -Order: 50 -xref: package-cacher-service -Title: Package Cacher Moderation Service -Description: Information on the Package Cacher Moderation Service ---- - -> :choco-warning: **WARNING** -> -> This is a Work in Progress. Please check back later. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-cleaner.md b/input/en-us/community-repository/moderation/package-cleaner.md deleted file mode 100644 index 797dc71735..0000000000 --- a/input/en-us/community-repository/moderation/package-cleaner.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -Order: 40 -xref: package-cleaner-service -Title: Package Cleaner Moderation Service -Description: Information on the Package Cleaner Moderation Service ---- - -> :choco-warning: **WARNING** -> -> This is a Work in Progress. Please check back later. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-scanner.md b/input/en-us/community-repository/moderation/package-scanner.md deleted file mode 100644 index c4fa7c0804..0000000000 --- a/input/en-us/community-repository/moderation/package-scanner.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -Order: 30 -xref: package-scanner-service -Title: Package Scanner Moderation Service -Description: Information on the Package Scanner Moderation Service ---- - -> :choco-warning: **WARNING** -> -> This is a Work in Progress. Please check back later. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/index.md b/input/en-us/community-repository/moderation/package-validator/index.md deleted file mode 100644 index 649b3f18af..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -Order: 10 -xref: package-validator -Title: Package Validator Moderation Service -Description: Information on the Package Validator Moderation Service ---- - -Here you will find a collection of more information and resources for when things fail validation. A comprehensive set of how items are reviewed is found at [the moderation docs](xref:moderation#requirements). - -> :choco-info: **NOTE** -> -> If you find you are getting flagged for many of these items, you should consider using choco new to generate and adapt updated templates that have all of the latest recommendations. - -What is the validator? -The validator is a service that checks the quality of a package based on requirements, guidelines and suggestions for creating packages for Chocolatey’s community feed. We like to think of the validator as unit testing. It is validating that everything is as it should be and meets the minimum requirements for a package on the community feed. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0001.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0001.md deleted file mode 100644 index 7a3b32ce90..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0001.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 1 -xref: cpmr0001 -Title: CPMR0001 - Copyright Character Count Below 4 (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0001 -RuleType: Requirement ---- - - - -## Issue - -In the nuspec, there is a `` field. Usually a copyright contains year (or range of years) and a company. Since a year takes up four characters by itself, the validator has detected that you are not using the copyright field correctly. - -## Recommended Solution - -Please update the copyright field so that it is using at least 4 characters. - -## Reasoning - -Usually the year alone takes up four characters, so properly setting a copyright would include years and name of company. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0002.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0002.md deleted file mode 100644 index db26a7f340..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0002.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -Order: 2 -xref: cpmr0002 -Title: CPMR0002 - Description Missing (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0002 -RuleType: Requirement ---- - - - -## Issue -In the nuspec, there is a `` element. It was found to be missing or empty in the package. - -## Recommended Solution - -Please update the nuspec to include a `` element that is non-empty. If your nuspec file is missing this field, you should run `choco new testpkg` and look at the output from that (ensure you have the [latest version of Chocolatey](https://community.chocolatey.org/packages?q=id%3Achocolatey)). - -## Reasoning - -The description explains the underlying software. Without any information, folks may not know what they are installing. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0003.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0003.md deleted file mode 100644 index fa5c7b3c7b..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0003.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 3 -xref: cpmr0003 -Title: CPMR0003 - Install Script Named Incorrectly (package) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0003 -RuleType: Requirement ---- - - - -## Issue - -Your script is named incorrectly and will need to be renamed. A script named `chocolateyInstall.ps1` was not found in your package, but another script ending in `install.ps1` was found. - -## Recommended Solution - -The install script should be named `chocolateyInstall.ps1` and be found in the tools folder. - -## Reasoning - -Chocolatey looks for a known/named script. Without it, Chocolatey can't run PowerShell automation. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0004.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0004.md deleted file mode 100644 index af290bfbe5..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0004.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -Order: 4 -xref: cpmr0004 -Title: CPMR0004 - Do Not Package Internal Files (package) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0004 -RuleType: Requirement ---- - - - -## Issue - -You have repackaged an existing package that you unpacked without removing some of the packaging files from the original. - -## Recommended Solution - -Please remove the following files: - -* [Content_Types].xml -* Files ending in .psmdcp -* Files ending .rels -* _rels directory and its contents - -## Reasoning - -The package will have issues if these are included again. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0005.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0005.md deleted file mode 100644 index def0c36b1d..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0005.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -Order: 5 -xref: cpmr0005 -Title: CPMR0005 - LICENSE.txt file missing when binaries included (package) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0005 -RuleType: Requirement ---- - - - -## Issue - -In the package, you have included binaries that you may have the right to distribute, but you have not included the license of the software to verify that. - -## Recommended Solution - -Please add the a file named LICENSE.txt. You can see the format for that file if you call `choco new test` and look at the generated file in `test\tools\LICENSE.txt` - -This check also looks for `LICENSE`, `LICENSE.md`, `NOTICE.txt`, `NOTICE`, and `NOTICE.md`. Casing doesn't matter for validation. - -## Reasoning - -It is not enough to point to the License Url in the package (although make sure you do that to if one exists), as the contents of the Url could change or go away over time. The contents of the package are permanent and folks need to understand the licensing that applies with the included binaries. It also a protection for you, the package maintainer, to ensure the legitimacy of having distribution rights for the software that you packaged at the time you packaged when it may need to be verified 5 years down the line. - -> :choco-info: **NOTE** -> -> If you received special permission to distribute, explain that in the LICENSE file and note the name of the permission file that is also included with the packaging. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0006.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0006.md deleted file mode 100644 index 9412c5c044..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0006.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 6 -xref: cpmr0006 -Title: CPMR0006 - VERIFICATION.txt file missing when binaries included (package) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0006 -RuleType: Requirement ---- - - - -## Issue - -In the package, you have included binaries but have not given moderators and the community a way to verify the files are legitimate. - -## Recommended Solution - -Please add a file named VERIFICATION.txt. You can see the format for that file if you call `choco new test` (upgrade to the latest version of Chocolatey first) and look at the generated file in `test\tools\VERIFICATION.txt` - -This check also looks for `VERIFICATION` and `VERIFICATION.md`. Casing doesn't matter for validation. - -## Reasoning - -If you include binaries in the package, even if you are the software vendor, you need to include a VERIFICATION.txt file. This allows moderators and the community build trust in using the package. A verification file tells folks how to verify the files are legitimate with specific instructions on verifying with the official location. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0007.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0007.md deleted file mode 100644 index fdb8acf38e..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0007.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 7 -xref: cpmr0007 -Title: CPMR0007 - License Url Missing / License Acceptance is True (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0007 -RuleType: Requirement ---- - - - -## Issue - -In the nuspec, there is a `` element. It was found to be missing or empty in the package. - -## Recommended Solution - -Please update the nuspec to include a `` element that is non-empty. If your nuspec file is missing this field, you should run `choco new testpkg` and look at the output from that (ensure you have the [latest version of Chocolatey](https://community.chocolatey.org/packages?q=id%3Achocolatey)). - -## Reasoning - -If you want to require license acceptance, you must include the license url. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0008.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0008.md deleted file mode 100644 index fa3d6f1d52..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0008.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 8 -xref: cpmr0008 -Title: CPMR0008 - Portable Package Uses Program Files (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0008 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0009.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0009.md deleted file mode 100644 index c006a8e027..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0009.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 9 -xref: cpmr0009 -Title: CPMR0009 - ProjectUrl Missing (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0009 -RuleType: Requirement ---- - - - -## Issue - -In the nuspec, there is a `` element. It was found to be missing or empty in the package. - -## Recommended Solution - -Please update the nuspec to include a `` element that is non-empty. If your nuspec file is missing this field, you should run `choco new testpkg` and look at the output from that (ensure you have the [latest version of Chocolatey](https://community.chocolatey.org/packages?q=id%3Achocolatey)). - -## Reasoning - -This is also known as the software site. Without this information, folks do not have anything to go on besides the package. On the community feed we want to ensure that folks have places to go for more information, the software site is a requirement. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0010.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0010.md deleted file mode 100644 index ddd000f1ea..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0010.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -Order: 10 -xref: cpmr0010 -Title: CPMR0010 - Script Contains Choco Commands (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0010 -RuleType: Requirement ---- - - - -## Issue - -In automation scripts (`.ps1`/`.psm1`), the package has used a chocolatey command that should not be used. Rather a dependency should be taken on a package. - - * cinst - * choco install - * choco upgrade - -> :choco-info: **NOTE** -> -> The search can also hit a false positive if it finds any of the above words in the package's automation scripts. - -## Recommended Solution - -Please add dependencies to the nuspec. - -## Reasoning - -Calling Chocolatey commands when running Chocolatey is considered an anti-pattern, and it hides dependency required for other packages, which should be expressed. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0011.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0011.md deleted file mode 100644 index b8190bef50..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0011.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 11 -xref: cpmr0011 -Title: CPMR0011 - Script Imports Chocolatey Module (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0011 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0012.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0012.md deleted file mode 100644 index 381aaa74a7..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0012.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 12 -xref: cpmr0012 -Title: CPMR0012 - Script Uses Internal Variables (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0012 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0013.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0013.md deleted file mode 100644 index 6775b66f98..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0013.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 13 -xref: cpmr0013 -Title: CPMR0013 - Source Control Files Are Packaged (package) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0013 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the package, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0014.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0014.md deleted file mode 100644 index f7a8757c3e..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0014.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 14 -xref: cpmr0014 -Title: CPMR0014 - Tags Have Commas (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0014 -RuleType: Requirement ---- - - - -## Issue - -In the nuspec in the `` element, the verifier found that the tags were separated with commas. They should only be separated with spaces. - -## Recommended Solution - -Please remove the commas from the `` element. - -## Reasoning - -We could just fix this on Chocolatey.org, but tags are used in other places besides just Chocolatey.org, and they are expected to be space separated. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0015.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0015.md deleted file mode 100644 index c8f79985d7..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0015.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 15 -xref: cpmr0015 -Title: CPMR0015 - Uninstall Script Named Incorrectly (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0015 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0016.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0016.md deleted file mode 100644 index d974403ee5..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0016.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -Order: 16 -xref: cpmr0016 -Title: CPMR0016 - Script Contains Usage of Installation Arguments (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0016 -RuleType: Requirement ---- - - - -## Issue - -In an automation script (`.ps1`/`.psm1`), the use of `chocolateyInstallArguments` was found. - -## Recommended Solution - -The package should instead use package parameters - see [How to Parse Package Parameters](xref:parse-package-parameters) and an example package to review for how to add information to the description would be the [Git package](https://community.chocolatey.org/packages/git). - -## Reasoning - -InstallArguments is meant to be a transparent variable that is passed right to a Chocolatey install helper function. If it is called in the script it could be misused or changed. Therefore we don't allow it in scripts. - -Another pattern: - -~~~powershell -$installArguments = $env:chocolateyInstallArguments -if ([string]::IsNullOrEmpty($installArguments )) { - $installArguments = " /Q /IAcceptSQLServerLicenseTerms /ACTION=install /INSTANCEID=SQLEXPRESS /INSTANCENAME=SQLEXPRESS /UPDATEENABLED=FALSE " -} -~~~ - -This behavior is unnecessary as Chocolatey already does this in the background. All you need to do in the script is set the install arguments. - -~~~powershell -$installArguments = " /Q /IAcceptSQLServerLicenseTerms /ACTION=install /INSTANCEID=SQLEXPRESS /INSTANCENAME=SQLEXPRESS /UPDATEENABLED=FALSE " -~~~ - -The consumer will decide to override install arguments or append to the current set with `--install-arguments`/`--ia` and `--override-arguments`/`-o`, see the [install command docs](xref:choco-command-install#options-and-switches) diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0017.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0017.md deleted file mode 100644 index d431c4214e..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0017.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 17 -xref: cpmr0017 -Title: CPMR0017 - Deprecated Packages Must Have A Dependency (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0017 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0018.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0018.md deleted file mode 100644 index e4be46c11a..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0018.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 18 -xref: cpmr0018 -Title: CPMR0018 - Install Script Shouldn't Call Uninstall Script (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0018 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0019.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0019.md deleted file mode 100644 index 3653f5449d..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0019.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 19 -xref: cpmr0019 -Title: CPMR0019 - Nuspec Contains Templated Values (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0019 -RuleType: Requirement ---- - - - -## Issue - -In the nuspec, templates values that were added by Chocolatey CLI have been left in the file. These values are not considered to be valid information, and only a placeholder for what users can make use of. - -## Recommended Solution - -Any templated values given by Chocolatey CLI should be replaced with an appropriate value for the Software the Package is responsible for, or removed if no proper information is available. - -## Reasoning - -As these are informations given to users, having such invalid placeholders in the nuspec file only serves to confuse users and cause packages to be considered of bad quality. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0020.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0020.md deleted file mode 100644 index 0d4369239e..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0020.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 20 -xref: cpmr0020 -Title: CPMR0020 - Nuspec Contains Email (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0020 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0021.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0021.md deleted file mode 100644 index b5215f7a92..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0021.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 21 -xref: cpmr0021 -Title: CPMR0021 - Operating System Index Files are packaged (package) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0021 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0022.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0022.md deleted file mode 100644 index 67fb366daf..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0022.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 22 -xref: cpmr0022 -Title: CPMR0022 - Comments Are Not Cleaned Up (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0022 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0023.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0023.md deleted file mode 100644 index e25631a599..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0023.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 23 -xref: cpmr0023 -Title: CPMR0023 - Tags Missing (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0023 -RuleType: Requirement ---- - - - -## Issue - -In the nuspec, there is a `` element. It was found to be missing or empty in the package. - -## Recommended Solution - -Please update the nuspec to include a `` element that is non-empty. If your nuspec file is missing this field, you should run `choco new testpkg` and look at the output from that (ensure you have the [latest version of Chocolatey](https://community.chocolatey.org/packages?q=id%3Achocolatey)). - -## Reasoning - -Tags aid in categorization of packages and underlying software. Tags should be relevant to the software that is being installed. It will give folks more options when searching for particular software on the site and may turn up in results it may have not otherwise came up in. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0024.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0024.md deleted file mode 100644 index 548b852d33..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0024.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 24 -xref: cpmr0024 -Title: CPMR0024 - Prerelease information shouldn't be included as part of Package Id (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0024 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -The `` field in the package `.nuspec` file, contains a prerelease version name such as `alpha`, `beta`, etc. - -## Recommended Solution - -Please update the `` field in the `.nuspec` file to ensure it only contains the name. The prerelease version name should be added to the `` field. Prerelease packages can be [installed](https://docs.chocolatey.org/en-us/choco/commands/install#options-and-switches) or [upgraded](https://docs.chocolatey.org/en-us/choco/commands/upgrade#options-and-switches) using the `--pre` option in Chocolatey CLI. - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0025.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0025.md deleted file mode 100644 index 8af415b3cf..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0025.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 25 -xref: cpmr0025 -Title: CPMR0025 - Source Control Ignore Files Are Packaged (package) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0025 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0026.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0026.md deleted file mode 100644 index 5c721b8748..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0026.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 26 -xref: cpmr0026 -Title: CPMR0026 - Description Character Count Above 4000 (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0026 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0027.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0027.md deleted file mode 100644 index cc293b2414..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0027.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -Order: 27 -xref: cpmr0027 -Title: CPMR0027 - Checksum Should Be Used (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0027 -RuleType: Requirement ---- - - - -> :choco-warning: **WARNING** -> -> This rule has not yet been implemented in package-validator. There is an [open issue](https://github.com/chocolatey/home/issues/31) that is tracking this addition. - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0028.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0028.md deleted file mode 100644 index 009a88da3f..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0028.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -Order: 28 -xref: cpmr0028 -Title: CPMR0028 - Scripts Do Not Download Software From FossHub (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0028 -RuleType: Requirement ---- - - - -## Issue - -In automation scripts (`.ps1`/`.psm1`), the package has attempted to download software from FossHub. FossHub has expressed a desire for this not to happen. They offset the costs of bandwidth with ad revenue and cannot make up for those bandwidth costs when a script does the downloading instead of a human who visits the page to download the software. - -## Recommended Solution(s) - -### Option 1 - Alternative Official Locations - -Look for an alternative download location that is legitimate. - -### Option 2 - Embed if Software Vendor's License Allows (Recommended) - -Please check the licensing for the software to determine if it allows embedding the software directly in the package. This is redistribution rights that the vendor will grant directly or through the license for the software. Many open sources licenses allow redistribution without modification. - -Should you decide to embed, you will also need to include both a -VERIFICATION.txt and a LICENSE.txt file. To see what those look like, please run `choco new test` with a recent version of Chocolatey. - -Chocolatey packages on the community repository can be up to 150MB. - -### Option 3 - No Package for that Software on the Community Repository - -If there is no alternate location and the software vendor does not grant the right to embed, indirectly through licensing or directly through communication with them, then the package is not able to be hosted on the community site. - -## Reasoning - -Recently (02 DEC 2016), we learned that FossHub had a desire not to have packages download software from their site because it was causing them significant financial distress based on not being able to make up for the bandwidth costs with ad revenue. They have every right to make this request and the Chocolatey community has a due diligence to respect this. - -Many maintainers on the Chocolatey community side tend to err on the side of legal protection by downloading the software from the official distribution location (aka FossHub and other hosting locations), whether or not it is necessary - sometimes the licensing from software allows for redistribution. While not doing anything technically illegal by disambiguating the download location, it may violate FossHub's terms of use. While this is not technically a good steward on the community's part, violating terms of use is the lesser of issues compared to illegally redistributing software (redistribution without permission has a legal recourse). - -Since it is by far easier to just default to what provides the most protection, even if a software license allows otherwise, this is what folks were doing. It's the least common denominator. Right or wrong, it's human psychology. - -> :choco-info: **NOTE** -> -> We don't condone the way the message was conveyed nor the way that FossHub attacked Chocolatey when a community member simply asked for an alternative download location on the Audacity forums. Folks in the Chocolatey community should respect the wishes of FossHub and also refrain from name calling or other things that would reflect poorly on the community in general. I implore you to look past their methods of communicating the situation and only the message that has been conveyed - "Please help us keep our costs down by not using scripts to download software from our site." diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0029.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0029.md deleted file mode 100644 index 980d9be3d6..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0029.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 29 -xref: cpmr0029 -Title: CPMR0029 - Package Id Does Not End With .config (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0029 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0030.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0030.md deleted file mode 100644 index 7ac80ea117..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0030.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -Order: 30 -xref: cpmr0030 -Title: CPMR0030 - Description Contains Invalid Markdown Heading (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0030 -RuleType: Requirement ---- - - - -## Issue - -The Description element of the package nuspec file contains invalid Markdown headings. For example, you may have this: - -``` -###This is my heading -``` -instead of: - -``` -### This is my heading -``` - -## Recommended Solution - -Please update the description element of the nuspec file to contain valid Markdown Headings. More information can be found [here](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#headers). - -## Reasoning - -The Chocolatey Community Repository uses the Markdig Library for parsing/rendering Markdown content. When invalid headings are used, the result looks like the following: - -![Example of invalid markdown from nuspec description rendering on the website](/assets/images/moderation/invalid-markdown-rendering.png) - -A prior version of the Chocolatey Community Repository did support this way for writing headings, but it is not part of the official Markdown specification, and as such, we don't want any further invalid headings making their way into the repository. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0031.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0031.md deleted file mode 100644 index 26494a32ee..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0031.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -Order: 31 -xref: cpmr0031 -Title: CPMR0031 - Invalid URL (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0031 -RuleType: Note ---- - - - -## Issue - -In the nuspec, one of the URLs provided is invalid. Usually this means that the URL does not actually go to a website. - -The following URL's, if invalid, will be marked as a Note. - -* bugTrackerUrl - Note -* docsUrl - Note -* iconUrl - Note -* licenseUrl - Note -* mailingListUrl - Note -* packageSourceUrl - Note -* projectSourceUrl - Note -* projectUrl - Note -* wikiUrl - Note - -> :choco-info: **NOTE** -> -> Within the Description and ReleaseNotes elements, all URL's contained within them will be validated. - -## Recommended Solution - -Please update the incorrect field(s) so that it results in a valid URL. - -## Reasoning - -We expect that the URLs actually go to an existing URL - -## Troubleshooting - -We have worked through a number of issues where valid URL were actually being flagged as invalid. If you believe that a valid URL within your nuspec file is being flagged as invalid, please reply on the package moderation page, and a moderator can help investigate. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0032.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0032.md deleted file mode 100644 index ea19c736a0..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0032.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -Order: 0032 -xref: cpmr0032 -Title: CPMR0032 - Description Character Count Below 30 (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0032 -RuleType: Requirement ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) -## Issue - -In the nuspec the description is less than the required amount of characters. - -## Recommended Solution - -Update the description for the package to include a description that has more than 30 characters. - -## Reasoning - -It is not enough to just add a few words to the description. -The description should be sufficient enough to explain what the software that is packaged is, and why people should use the software. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0033.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0033.md deleted file mode 100644 index b16b5885bd..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0033.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 0033 -xref: cpmr0033 -Title: CPMR0033 - IconUrl Missing (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0033 -RuleType: Guideline ---- - - - -## Issue - -The nuspec is missing (or has commented out) the `iconUrl`, which points to an icon image for the underlying software the package is based on. If there is an existing icon/logo for the software, it should be included with the package. - -## Recommended Solution - -Add `url_here` to the nuspec following the [icon guidelines](xref:create-packages#package-icon-guidelines). If your nuspec file is missing this field, you should run `choco new testpkg` and look at the output from that (ensure you have the [latest version of Chocolatey](https://community.chocolatey.org/packages?q=id%3Achocolatey)). - -## Reasoning - -We really want to see the IconUrl being used. It adds to the quality of the package when it has an icon to show. It is best to provide the icon from a source you control such as your GitHub repository, however GitHub raw is not intended to serve as a CDN. So please use a static CDN service. For further information on how to setup your icon with a CDN URL, please see [icon guidelines](xref:create-packages#package-icon-guidelines). It's not as intuitive as you might hope. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0034.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0034.md deleted file mode 100644 index d6cb3bada1..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0034.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -Order: 0034 -xref: cpmr0034 -Title: CPMR0034 - Use of SourceForge (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0034 -RuleType: Guideline ---- - - - -## Issue - -In an automation script (`.ps1`/`.psm1`), the use of sourceforge was found for downloading software. It is not recommended to use SourceForge if an alternative, official distribution location is available. Unfortunately, some software is only available on SourceForge so this is a Guideline and not a Requirement. - -> :choco-info: **NOTE** -> -> You may not be able to change this and this is okay. - -> :choco-info: **NOTE** -> -> The search can also hit a false positive if it finds any of the following words in your automation scripts (`ps1`/`psm1`): -> * sourceforge - -## Recommended Solution - -Please find another official distribution point to download from if there is one. - -## Reasoning - -We've found that SourceForge has had some practices in recent times that are at odds with how we want to get software installed (malware free). Usually when installing silently, software doesn't also try to install crapware on a machine. This is not always so with the sourceforge wrapper that comes along with some of these downloads. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0035.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0035.md deleted file mode 100644 index 8b95d46062..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0035.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -Order: 0035 -xref: cpmr0035 -Title: CPMR0035 - Use of Get-BinRoot (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0035 -RuleType: Guideline ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Replace all uses of the cmdlet `Get-BinRoot` to use `Get-ToolsLocation` instead. - -## Reasoning - -The PowerShell cmdlet is badly named, and was replaced with a new cmdlet called `Get-ToolsLocation` instead. -The cmdlet is also deprecated in version 1.0.0 of Chocolatey and will be removed in version 2.0.0 so any calls -to the cmdlet should no longer be made. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0036.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0036.md deleted file mode 100644 index e79d6203dd..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0036.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0036 -xref: cpmr0036 -Title: CPMR0036 - Install-BinFile With No Remove-BinFile (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0036 -RuleType: Guideline ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0037.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0037.md deleted file mode 100644 index a2863ddda1..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0037.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -Order: 0037 -xref: cpmr0037 -Title: CPMR0037 - Custom Action In Install With No Uninstall (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0037 -RuleType: Guideline ---- - - - -## Issue - -In automation scripts (`.ps1`/`.psm1`), the package has used one of the below items without also including a `chocolateyUninstall.ps1` to remove any thing changed by those items. - - * Install-ChocolateyPath - * Install-ChocolateyEnvironmentVariable - * Install-ChocolateyExplorerMenuItem - * Install-ChocolateyShortcut - * Install-ChocolateyFileAssociation - * Install-BinFile / Generate-BinFile / Add-BinFile - -> :choco-info: **NOTE** -> -> The search can also hit a false positive if it finds any of the above words in the package's automation scripts. - -## Recommended Solution - -Please add a `chocolateyUninstall.ps1` and reverse any install actions in the uninstall. - -## Reasoning - -The above items put the computer/machine they are installing to in a certain state. When the package is removed or uninstalled, the underlying changes to the machine should go away as well. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0038.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0038.md deleted file mode 100644 index 27a1c17c15..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0038.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0038 -xref: cpmr0038 -Title: CPMR0038 - LicenseUrl Matches ProjectUrl (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0038 -RuleType: Guideline ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0039.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0039.md deleted file mode 100644 index 87f1e548a2..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0039.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 0039 -xref: cpmr0039 -Title: CPMR0039 - LicenseUrl Missing (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0039 -RuleType: Guideline ---- - - - -## Issue - -In the nuspec, there is a `` element. It was found to be missing or empty in the package. - -## Recommended Solution - -Please update the nuspec to include a `` element that is non-empty. If your nuspec file is missing this field, you should run `choco new testpkg` and look at the output from that (ensure you have the [latest version of Chocolatey](https://community.chocolatey.org/packages?q=id%3Achocolatey)). - -## Reasoning - -It is strongly encouraged to let folks know what licensing the particular underlying software from installing the package will carry so that decisions can be made ahead of time if it fits within the parameters of what the user can use depending on the setting they are in. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0040.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0040.md deleted file mode 100644 index 82c5a72efe..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0040.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 0040 -xref: cpmr0040 -Title: CPMR0040 - PackageSourceUrl Missing (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0040 -RuleType: Guideline ---- - - - -## Issue - -In the nuspec, a `` was not found to exist. This is the url to the chocolatey package repository, not the software (unless they are the same). - -## Recommended Solution - -Please add `packageSourceUrl`, pointing to the url where the Chocolatey package source resides. You must use `choco pack` with at least version [0.9.9.7](https://docs.chocolatey.org/en-us/choco/release-notes#june-20-2015) (see [#205](https://github.com/chocolatey/choco/issues/205)) to do this. Using NuGet or `nuget.exe` will error on this element. If your nuspec file is missing this field, you should run `choco new testpkg` and look at the output from that (ensure you have the [latest version of Chocolatey](https://community.chocolatey.org/packages?q=id%3Achocolatey)). - -## Reasoning - -`packageSourceUrl` allows potential collaborators to easily find your package source so they can provide fixes. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0041.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0041.md deleted file mode 100644 index f1afc61fe8..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0041.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0041 -xref: cpmr0041 -Title: CPMR0041 - ProjectSourceUrl Matches ProjectUrl (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0041 -RuleType: Guideline ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0042.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0042.md deleted file mode 100644 index ae0029c7a9..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0042.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 0042 -xref: cpmr0042 -Title: CPMR0042 - ReleaseNotes Missing (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0042 -RuleType: Guideline ---- - - - -## Issue - -In the nuspec, there is a `` element. It was found to be missing or empty in the package. - -## Recommended Solution - -Please update the nuspec to include a `` element that is non-empty. If your nuspec file is missing this field, you should run `choco new testpkg` and look at the output from that as a comparison to your current package (ensure you have the [latest version of Chocolatey](https://community.chocolatey.org/packages?q=id%3Achocolatey)). - -## Reasoning - -The release notes field gives folks a way of knowing what has changed between versions of the software (and sometimes related to packaging changes). diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0043.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0043.md deleted file mode 100644 index ee162bcfed..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0043.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0043 -xref: cpmr0043 -Title: CPMR0043 - Script Is Too Long (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0043 -RuleType: Guideline ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0044.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0044.md deleted file mode 100644 index 447902840a..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0044.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0044 -xref: cpmr0044 -Title: CPMR0044 - Script Contains Install-ChocolateyDesktopLink (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0044 -RuleType: Guideline ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0045.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0045.md deleted file mode 100644 index 06cd68048a..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0045.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0045 -xref: cpmr0045 -Title: CPMR0045 - Script Contains Write-Chocolatey* Method (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0045 -RuleType: Guideline ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0046.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0046.md deleted file mode 100644 index 8b70c9648c..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0046.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0046 -xref: cpmr0046 -Title: CPMR0046 - Script Contains Start-Process (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0046 -RuleType: Guideline ---- - - - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0047.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0047.md deleted file mode 100644 index 5b93b8801d..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0047.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 0047 -xref: cpmr0047 -Title: CPMR0047 - Summary Missing (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0047 -RuleType: Guideline ---- - - - -## Issue - -In the nuspec, there is a `` element. It was found to be missing or empty in the package. - -## Recommended Solution - -Please update the nuspec to include a `` element that is non-empty. If your nuspec file is missing this field, you should run `choco new testpkg` and look at the output from that (ensure you have the [latest version of Chocolatey](https://community.chocolatey.org/packages?q=id%3Achocolatey)). - -## Reasoning - -The summary gives a high level explanation that is a sentence explaining what the software is. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0048.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0048.md deleted file mode 100644 index aad712c513..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0048.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 0048 -xref: cpmr0048 -Title: CPMR0048 - Tags Contain Chocolatey (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0048 -RuleType: Guideline ---- - - - -## Issue - -In the nuspec, there is a `` element that contains `chocolatey` as one of the values. - -## Recommended Solution - -Please update the nuspec to remove `chocolatey` from the list of tags. - -## Reasoning - -Tags are about the underlying software. If that software has little or nothing to do with Chocolatey, there is no reason to carry the `chocolatey` tag. The `chocolatey` tag is specifically for things that are about Chocolatey and its framework, not about packages that can be installed with Chocolatey. If the purpose was for packages that are Chocolatey compatible, every package on https://community.chocolatey.org/packages would contain `chocolatey` for a tag and thus reduce the usefulness of the tag. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0049.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0049.md deleted file mode 100644 index fe0d3b8fb2..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0049.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 0049 -xref: cpmr0049 -Title: CPMR0049 - Title Missing (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0049 -RuleType: Guideline ---- - - - -## Issue - -In the nuspec, there is a `` element. It was found to be missing or empty in the package. - -## Recommended Solution - -Please update the nuspec to include a `<title />` element that is non-empty. If your nuspec file is missing this field, you should run `choco new testpkg` and look at the output from that (ensure you have the [latest version of Chocolatey](https://community.chocolatey.org/packages?q=id%3Achocolatey)). - -## Reasoning - -A title is a more description version of your package id - where your package id may be something like `jjb` - the title would be `Jenkins Job Builder`. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0050.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0050.md deleted file mode 100644 index 8448716840..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0050.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -Order: 0050 -xref: cpmr0050 -Title: CPMR0050 - Title Matches Id (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0050 -RuleType: Guideline ---- - -<?! Include "../../../../../shared/package-validator-rule-guideline.txt" /?> - -> :choco-warning: **WARNING** -> -> There was a bug where it was not taking case into account. We've fixed the bug, but you may end up here - https://github.com/chocolatey/home/issues/32 - -## Issue - -In the nuspec, the id of the package `<id />` was found to match exactly with `<title />`. - -## Recommended Solution - -In the nuspec, ensure the `<id />` is completely lowercase (e.g. "`thispackage`") and the `<title />` uses title case (e.g. "`This Package`"). - -## Reasoning - -In general, the id should be lowercase ("`thispackage`") and a title should have title case ("`ThisPackage`"). The names may match, but what we are generally searching for is whether someone has ran the template generation and then forgotten to update the title in the nuspec to something more appropriate. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0051.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0051.md deleted file mode 100644 index f84f704640..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0051.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -Order: 0051 -xref: cpmr0051 -Title: CPMR0051 - More Than 3 Installation Scripts (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0051 -RuleType: Guideline ---- - -<?! Include "../../../../../shared/package-validator-rule-guideline.txt" /?> - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning - -If a package is doing all kinds of complicated things, that could be better served as an enhancement to Chocolatey helpers to reduce the amount of work necessary by a given package. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0052.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0052.md deleted file mode 100644 index ef9edd8c0f..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0052.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -Order: 0052 -xref: cpmr0052 -Title: CPMR0052 - Dependency With No Version (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0052 -RuleType: Guideline ---- - -<?! Include "../../../../../shared/package-validator-rule-guideline.txt" /?> - -> :choco-warning: **WARNING** -> -> There is a bug with this check - https://github.com/chocolatey/home/issues/33 - -If you have implemented the recommended fixes, you should see this go away on checks after this has been corrected. - -## Issue - -In the nuspec, you have a dependency on another package without at the very least a minimum version. - -## Recommended Solution - -Version-less dependencies are not recommended now that choco will resolve the latest version of a package. Please add at the very least the minimum version (also known as the lower bound) of the package you depend on. Note how version ranges work, see http://docs.nuget.org/Create/versioning#Specifying-Version-Ranges-in-.nuspec-Files - -## Reasoning - -At a point in history, NuGet would always get the oldest version of a package that would meet the version range that was specified. When you didn't specify a version, it would get the latest possible version. Once choco 0.9.9+ came out, it flipped NuGet to always getting the most recent version of a package that satisfied a dependency. It's considered incorrect to not at the very least specify a minimum version that would meet a dependency. This way it is more explicit. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0053.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0053.md deleted file mode 100644 index 29d8a323b1..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0053.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0053 -xref: cpmr0053 -Title: CPMR0053 - Deprecated Package Title Should Start With [Deprecated] (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0053 -RuleType: Guideline ---- - -<?! Include "../../../../../shared/package-validator-rule-guideline.txt" /?> - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0054.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0054.md deleted file mode 100644 index af3de06d60..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0054.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0054 -xref: cpmr0054 -Title: CPMR0054 - Nuspec File Should Be UTF-8 (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0054 -RuleType: Guideline ---- - -<?! Include "../../../../../shared/package-validator-rule-guideline.txt" /?> - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0055.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0055.md deleted file mode 100644 index 339e7275ac..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0055.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -Order: 0055 -xref: cpmr0055 -Title: CPMR0055 - Script Uses Custom Downloaders (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0055 -RuleType: Guideline ---- - -<?! Include "../../../../../shared/package-validator-rule-guideline.txt" /?> - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -0.9.10 supports passing headers to Get-ChocolateyWebFile and other methods that download. - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0056.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0056.md deleted file mode 100644 index 2d7168301e..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0056.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -Order: 0056 -xref: cpmr0056 -Title: CPMR0056 - Invalid URL (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0056 -RuleType: Guideline ---- - -<?! Include "../../../../../shared/package-validator-rule-guideline.txt" /?> - -## Issue - -In the nuspec, one of the URLs provided is invalid. Usually this means that the URL does not actually go to a website. - -The following URL's, if invalid, will be marked as a Guideline (would be good if it could be fixed). - -* description - Guideline -* releaseNotes - Guideline - -> :choco-info: **NOTE** -> -> Within the Description and ReleaseNotes elements, all URL's contained within them will be validated. - -## Recommended Solution - -Please update the incorrect field(s) so that it results in a valid URL. - -## Reasoning - -We expect that the URLs actually go to an existing URL - -## Troubleshooting - -We have worked through a number of issues where valid URL were actually being flagged as invalid. If you believe that a valid URL within your nuspec file is being flagged as invalid, please reply on the package moderation page, and a moderator can help investigate. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0057.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0057.md deleted file mode 100644 index 2ad013cd7b..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0057.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -Order: 0057 -xref: cpmr0057 -Title: CPMR0057 - Nuspec Enhancements Missing (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0057 -RuleType: Suggestion ---- - -<?! Include "../../../../../shared/package-validator-rule-suggestion.txt" /?> - -## Issue - -The nuspec is missing the recent enhancements that give consumers information related to the underlying software. - -## Recommended Solution - -Please update the nuspec to contain one or more of the following: - - * `docsUrl` - points to the location of the wiki or docs of the software - * `mailingListUrl` - points to the forum or email list group for the software - * `bugTrackerUrl` - points to the location where issues and tickets can be accessed - * `packageSourceUrl` - points to the location of your chocolatey package files in source (e.g. `https://github.com/chocolatey-community/chocolatey-packages`) - * `projectSourceUrl` - points to the location of the underlying software source - -> :choco-info: **NOTE** -> -> You must use `choco pack` with at least version [0.9.9.7](https://docs.chocolatey.org/en-us/choco/release-notes#june-20-2015) (see [#205](https://github.com/chocolatey/choco/issues/205)) to use these elements. Using NuGet or `nuget.exe` will error on this element. - -> :choco-info: **NOTE** -> -> If your nuspec file is missing these fields, you should run `choco new testpkg` and look at the output from that (ensure you have the [latest version of Chocolatey](https://community.chocolatey.org/packages?q=id%3Achocolatey)). - -## Reasoning - -This provides folks with more information related to the software itself and gives folks a quick location reference to start from when attempting to find more information related to a project. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0058.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0058.md deleted file mode 100644 index 8e7d68b325..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0058.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0058 -xref: cpmr0058 -Title: CPMR0058 - Use PNG or SVG for package icons (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0058 -RuleType: Suggestion ---- - -<?! Include "../../../../../shared/package-validator-rule-suggestion.txt" /?> - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0059.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0059.md deleted file mode 100644 index 86892b8c04..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0059.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -Order: 0059 -xref: cpmr0059 -Title: CPMR0059 - Don't Use Get-WmiObject For Finding Installed Packages (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0059 -RuleType: Suggestion ---- - -<?! Include "../../../../../shared/package-validator-rule-suggestion.txt" /?> - -## Issue - -In an automation script (`.ps1`/`.psm1`), you used `Win32_Product`. This can cause serious performance issues and have an adverse affect on Windows. - -## Recommended Solution - -Instead do a registry search under Uninstaller to see if the application is installed. - -## Reasoning - -"Win32_Product" forces Windows Installer to reconfigure every application installed through MSI (see Windows event log). Depending on installed applications it may take more than 30 minutes to execute a request. - -* http://gregramsey.net/2012/02/20/win32_product-is-evil/ -* https://sdmsoftware.com/group-policy-blog/wmi/why-win32_product-is-bad-news/ -* http://csi-windows.com/toolkit/win32product-replacement diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0060.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0060.md deleted file mode 100644 index 6e8a03d07d..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0060.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -Order: 0060 -xref: cpmr0060 -Title: CPMR0060 - Binaries Included (package) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0060 -RuleType: Note ---- - -<?! Include "../../../../../shared/package-validator-rule-note.txt" /?> - -## Issue - -In the package, you have included binaries that match one of the following extensions: - -* exe -* msi -* msu -* msp -* dll -* 7z -* zip -* gz -* tar -* rar -* sfx -* iso -* dmg -* so -* jar - -## Recommended Solution - -Please remove the binaries or update the package with a [license file](xref:cpmr0005) and a [verification file](xref:cpmr0006). - -## Reasoning - -If you include binaries in the package, even if you are the software vendor, you need to include confirmation of the right to distribute and verification that the files are legitimate. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0061.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0061.md deleted file mode 100644 index 63bf8c3209..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0061.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0061 -xref: cpmr0061 -Title: CPMR0061 - Id Contains "." (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0061 -RuleType: Note ---- - -<?! Include "../../../../../shared/package-validator-rule-note.txt" /?> - -## Issue - -The package id includes dots and has not been found to be an `*.install`/`*.portable` package. - -## Recommended Solution - -If this is a new package that has never been approved, moderators will review and reject the package for one that will be pushed with a new id that meets the [package naming guidelines](xref:create-packages#naming-your-package). - -If this is an already existing package, there is really nothing you can do at this time aside from deprecate the current package in favor of a newly created one. Please see [deprecating a package](xref:deprecate-a-package) - -## Reasoning - -Naming should be consistent for packages on the community feed so it's easy to understand. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0062.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0062.md deleted file mode 100644 index 4112f57890..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0062.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -Order: 0062 -xref: cpmr0062 -Title: CPMR0062 - Chocolatey Dependency (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0062 -RuleType: Note ---- - -<?! Include "../../../../../shared/package-validator-rule-note.txt" /?> - -## Issue - -In the nuspec, one or more dependencies were found, and one of them depends on the Chocolatey CLI package (`chocolatey`). - -## Recommended Solution - -Please ensure that you are using and requiring the functionality of the Chocolatey CLI dependency version in one of your automation scripts. If no automation script requires functionality only available in the defined version, please remove this dependency. - -## Reasoning - -Specifying a dependency on Chocolatey CLI is considered an antipattern and can have repercussions when a package is uninstalled while the user decides to also remove their dependencies at the same time. As such, a dependency on Chocolatey CLI should be used sparingly and only when needed. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0063.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0063.md deleted file mode 100644 index 90bd117181..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0063.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0063 -xref: cpmr0063 -Title: CPMR0063 - Usage of WScript (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0063 -RuleType: Note ---- - -<?! Include "../../../../../shared/package-validator-rule-note.txt" /?> - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0064.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0064.md deleted file mode 100644 index 12e7bb85fa..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0064.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0064 -xref: cpmr0064 -Title: CPMR0064 - Usage of .CreateShortcut (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0064 -RuleType: Note ---- - -<?! Include "../../../../../shared/package-validator-rule-note.txt" /?> - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0065.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0065.md deleted file mode 100644 index 85d8675821..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0065.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0065 -xref: cpmr0065 -Title: CPMR0065 - Usage of Rundll32 (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0065 -RuleType: Note ---- - -<?! Include "../../../../../shared/package-validator-rule-note.txt" /?> - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0066.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0066.md deleted file mode 100644 index 822fd37108..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0066.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0066 -xref: cpmr0066 -Title: CPMR0066 - Usage of msiexec (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0066 -RuleType: Note ---- - -<?! Include "../../../../../shared/package-validator-rule-note.txt" /?> - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In an automation script (`.ps1`/`.psm1`), - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0067.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0067.md deleted file mode 100644 index 34826cd903..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0067.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0067 -xref: cpmr0067 -Title: CPMR0067 - notSilent tag is being used (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0067 -RuleType: Note ---- - -<?! Include "../../../../../shared/package-validator-rule-note.txt" /?> - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0068.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0068.md deleted file mode 100644 index 02efb6c33d..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0068.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0068 -xref: cpmr0068 -Title: CPMR0068 - Author Does Not Match Maintainer (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0068 -RuleType: Note ---- - -<?! Include "../../../../../shared/package-validator-rule-note.txt" /?> - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0069.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0069.md deleted file mode 100644 index c813511484..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0069.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0069 -xref: cpmr0069 -Title: CPMR0069 - Package Id is too long, and doesn't contain dashes (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0069 -RuleType: Note ---- - -<?! Include "../../../../../shared/package-validator-rule-note.txt" /?> - -## Issue - -The package id is longer than 20 characters but does not include dashes (`-`) to break up the words to make it readable. - -## Recommended Solution - -If this is a new package that has never been approved, moderators will review and reject the package for one that will be pushed with a new id that meets the [package naming guidelines](xref:create-packages#naming-your-package). - -If this is an already existing package, there is really nothing you can do at this time aside from deprecate the current package in favor of a newly created one. Please see [deprecating a package](xref:deprecate-a-package) - -## Reasoning - -A name for a package id should be easily understandable. When it becomes really long with no breaks, it makes it hard to understand on first view where each word is. Consider that when folks see a package id, it will be in lowercase, e.g. `this-package-id` is easier to digest than `thispackageid`. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0070.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0070.md deleted file mode 100644 index dd6cd8a4aa..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0070.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -Order: 0070 -xref: cpmr0070 -Title: CPMR0070 - Package Id uses underscores (nuspec) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0070 -RuleType: Note ---- - -<?! Include "../../../../../shared/package-validator-rule-note.txt" /?> - -> :choco-info: **NOTE** -> -> This page is a stub that has not yet been filled out. If you have questions about this issue, please ask in the review or reach out on [Community Chat](https://ch0.co/community) - -## Issue - -In the nuspec, - -## Recommended Solution - -Please update _ so that _ - -## Reasoning diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0071.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0071.md deleted file mode 100644 index 1e99dcd85f..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0071.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -Order: 0071 -xref: cpmr0071 -Title: CPMR0071 - Script uses commercial cmdlets (script) -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0071 -RuleType: Requirement ---- - -<?! Include "../../../../../shared/package-validator-rule-requirement.txt" /?> - -## Issue - -In an automation script (`.ps1`/`.psm1`), one or more calls to a licensed function that is only available in licensed editions of Chocolatey, is being used. - -## Recommended Solution - -Please do not use licensed features when creating packages that you will submit to the Chocolatey Community Repository. Update all automation scripts to use functions that are available in open-source Chocolatey. - -## Reasoning - -Packages created with licensed features should not be made available in the Chocolatey Community Repository and are intended for use by organizations hosting their own internal package repository. -All packages submitted to the Chocolatey Community Repository are for the community and should work on all editions of Chocolatey. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0072.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0072.md deleted file mode 100644 index 6d9baa2115..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0072.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -Order: 0072 -xref: cpmr0072 -Title: CPMR0072 - Usage of Private Environment Variables -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0072 -RuleType: Requirement ---- - -<?! Include "../../../../../shared/package-validator-rule-requirement.txt" /?> - -## Issue - -In an automation script (`.ps1`/`.psm1`) the scripts make use of either reading or writing private environment variables that should only be used by Chocolatey CLI helpers and not the automation scripts themselves. - -## Recommended Solution - -Remove any use of the following environment variables in the automation scripts. - -- `chocolateyToolsLocation` -- `chocolateyBinRoot` -- `chocolatey_bin_root` -- `chocolateyPackageFolder` -- `packageFolder` -- `chocolateyChecksum32` -- `chocolateyChecksum64` -- `chocolateyChecksumType32` -- `chocolateyChecksumType64` -- `downloadCacheAvailable` - -### Chocolatey Tools Location - -Any usages of the `chocolateyToolsLocation`, `chocolateyBinRoot`, or `chocolatey_bin_root` can be replaced with a call to [Get-ToolsLocation](xref:get-toolslocation). The `Get-ToolsLocation` helper is a wrapper that will provide the same information as directly reading the environment variable, but it also ensures that the variable is created if it did not previously exist. - -### Chocolatey Package Folder - -Replace usages of `chocolateyPackageFolder` or `packageFolder` with `Get-ChocolateyPath -PathType 'PackagePath'`. See the documentation for [Get-ChocolateyPath](xref:get-chocolateypath) for more information on the helper. - -## Reasoning - -The variables are used by the Chocolatey CLI helpers by including additional support and should not be used by the automation scripts themselves. diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0073.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0073.md deleted file mode 100644 index c84c38003e..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0073.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -Order: 0073 -xref: cpmr0073 -Title: CPMR0073 - Script do not validate downloaded files -Description: Information on how to remediate the Chocolatey Package Moderation Rule 0073 -RuleType: Requirement ---- - -<?! Include "../../../../../shared/package-validator-rule-requirement.txt" /?> - -## Issue - -In an automation script (`.ps1`/`.psm1`), one or more calls that downloads files from a remote location are used without verifying the checksums of these files. - -The following helper functions are currently being validated by this rule, with possibly more being added in the future. - -- [`Install-ChocolateyPackage`](xref:install-chocolateypackage) - If the `Url` parameter is used, the associated `Checksum` parameter is additionally set (For 64bit this would be `Url64` / `Url64bit` and `Checksum64`). -- [`Install-ChocolateyZipPackage`](xref:install-chocolateyzippackage) - If the `Url` parameter is used, the associated `Checksum` parameter is additionally set (For 64bit this would be `Url64` / `Url64bit` and `Checksum64`). -- [`Get-ChocolateyWebFile`](xref:get-chocolateywebfile) - If the `Url` parameter is used, the associated `Checksum` parameter is additionally set (For 64bit this would be `Url64` / `Url64bit` and `Checksum64`). -- [`Install-ChocolateyPowershellCommand`](xref:install-chocolateypowershellcommand) - If the `Url` parameter is used, the associated `Checksum` parameter is additionally set (For 64bit this would be `Url64` / `Url64bit` and `Checksum64`). -- [`Install-ChocolateyVsixPackage`](xref:install-chocolateyvsixpackage) - If the `VsixUrl` / `Url` parameter is used, the associated `Checksum` parameter is additionally set. -- [`Get-WebFile`](xref:get-webfile) - A low-level download of a single file that should generally be avoided unless necessary, requires an additional call to `Get-ChecksumValid` using the same file name specified for the output. -- [`Get-FtpFile`](xref:get-ftpfile) - A low-level download of a single file that should generally be avoided unless necessary, requires an additional call to `Get-ChecksumValid` using the same file name specified for the output. - -## Recommended Solution - -Update all calls to helper functions that download files from a remote location to include the use of their respective `Checksum` property, or make a call to `Get-ChecksumValid` if no such parameter exists. - -## Reasoning - -All packages on the Chocolatey Community Repository should aim to be as safe and resilient as possible. -Adding a checksum when downloading remote files helps with the security that the file is the same as the maintainer created the package for, and it has not been changed during the request. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0074.md b/input/en-us/community-repository/moderation/package-validator/rules/cpmr0074.md deleted file mode 100644 index 2706622ef2..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/cpmr0074.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -Order: 0074 -xref: cpmr0074 -Title: CPMR0074 - Dependency On Hook Package (nuspec) ---- - -<?! Include "../../../../../shared/package-validator-rule-requirement.txt" /?> - -## Issue - -Within the nuspec, a dependency on a package with the `.hook` suffix was found. Packages, other than `.hook` packages, should not have such a dependency. - -## Recommended Solution - -Remove any dependency that specifies a package with a `.hook` suffix. - -## Reasoning - -Since a `.hook` package will introduce scripts that will be installed on the user's computer and run before or after any install, upgrade or uninstall that the user attempts, such packages should never be automatically installed. A user should explicitly opt into using such packages, and other packages should not go against this practice. \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-validator/rules/index.cshtml b/input/en-us/community-repository/moderation/package-validator/rules/index.cshtml deleted file mode 100644 index bd99500f5c..0000000000 --- a/input/en-us/community-repository/moderation/package-validator/rules/index.cshtml +++ /dev/null @@ -1,120 +0,0 @@ ---- -Order: 10 -xref: package-validator-rules -Title: Package Validator Rules -Description: Information on the Package Validator rules -HideChildPages: true ---- - -<p>There are 4 different types of Package Validator rules:</p> - -<ul> - <li><a href="#requirements">Requirements</a></li> - <li><a href="#guidelines">Guidelines</a></li> - <li><a href="#suggestions">Suggestions</a></li> - <li><a href="#notes">Notes</a></li> -</ul> - -<h2>Requirements</h2> - -<p>Requirements represent the minimum quality of a package that is acceptable. When a package version has failed requirements, the package version requires fixing and/or response by the maintainer. Provided a Requirement has flagged correctly, it must be fixed before the package version can be approved. The exact same version should be uploaded during moderation review.</p> - -<div class="row mt-3 mt-md-4 ms-md-n5 ms-xl-n3"> - @foreach (IDocument child in OutputPages.GetChildrenOf(Document).OnlyRequirements()) - { - object[] childTreePath = child.Get<object[]>(Keys.TreePath); - - <div class="col-lg-6 col-xl-4 pb-4"> - <div class="card card-body card-link card-index"> - <div class="circle"> - <i class="fa-solid fa-file" aria-hidden="true"></i> - </div> - <div class="d-flex flex-column ps-3"> - <p class="h5 fw-bold card-title"><a class="stretched-link" href="@child.GetLink()" title='@child.GetTitle()'>@child.GetTitle()</a></p> - @if (child.ContainsKey(WebKeys.Description)) - { - <p class="card-content">@(child.Get(WebKeys.Description))</p> - } - </div> - </div> - </div> - } -</div> - -<h2>Guidelines</h2> - -<p>Guidelines are strong suggestions that improve the quality of a package version. These are considered something to fix for next time to increase the quality of the package. Over time Guidelines can become Requirements. A package version can be approved without addressing Guideline comments but will reduce the quality of the package.</p> - -<div class="row mt-3 mt-md-4 ms-md-n5 ms-xl-n3"> - @foreach (IDocument child in OutputPages.GetChildrenOf(Document).OnlyGuidelines()) - { - object[] childTreePath = child.Get<object[]>(Keys.TreePath); - - <div class="col-lg-6 col-xl-4 pb-4"> - <div class="card card-body card-link card-index"> - <div class="circle"> - <i class="fa-solid fa-file" aria-hidden="true"></i> - </div> - <div class="d-flex flex-column ps-3"> - <p class="h5 fw-bold card-title"><a class="stretched-link" href="@child.GetLink()" title='@child.GetTitle()'>@child.GetTitle()</a></p> - @if (child.ContainsKey(WebKeys.Description)) - { - <p class="card-content">@(child.Get(WebKeys.Description))</p> - } - </div> - </div> - </div> - } -</div> - -<h2>Suggestions</h2> - -<p>Suggestions are either newly introduced items that will later become Guidelines or items that are don't carry enough weight to become a Guideline. Either way they should be considered. A package version can be approved without addressing Suggestion comments.</p> - -<div class="row mt-3 mt-md-4 ms-md-n5 ms-xl-n3"> - @foreach (IDocument child in OutputPages.GetChildrenOf(Document).OnlySuggestions()) - { - object[] childTreePath = child.Get<object[]>(Keys.TreePath); - - <div class="col-lg-6 col-xl-4 pb-4"> - <div class="card card-body card-link card-index"> - <div class="circle"> - <i class="fa-solid fa-file" aria-hidden="true"></i> - </div> - <div class="d-flex flex-column ps-3"> - <p class="h5 fw-bold card-title"><a class="stretched-link" href="@child.GetLink()" title='@child.GetTitle()'>@child.GetTitle()</a></p> - @if (child.ContainsKey(WebKeys.Description)) - { - <p class="card-content">@(child.Get(WebKeys.Description))</p> - } - </div> - </div> - </div> - } -</div> - -<h2>Notes</h2> - -<p>Notes typically flag things for both you and the reviewer to go over. Sometimes this is the use of things that may or may not be necessary given the constraints of what you are trying to do and/or are harder for automation to flag for other reasons. Items found in Notes might be Requirements depending on the context. A package version can be approved without addressing Note comments.</p> - -<div class="row mt-3 mt-md-4 ms-md-n5 ms-xl-n3"> - @foreach (IDocument child in OutputPages.GetChildrenOf(Document).OnlyNotes()) - { - object[] childTreePath = child.Get<object[]>(Keys.TreePath); - - <div class="col-lg-6 col-xl-4 pb-4"> - <div class="card card-body card-link card-index"> - <div class="circle"> - <i class="fa-solid fa-file" aria-hidden="true"></i> - </div> - <div class="d-flex flex-column ps-3"> - <p class="h5 fw-bold card-title"><a class="stretched-link" href="@child.GetLink()" title='@child.GetTitle()'>@child.GetTitle()</a></p> - @if (child.ContainsKey(WebKeys.Description)) - { - <p class="card-content">@(child.Get(WebKeys.Description))</p> - } - </div> - </div> - </div> - } -</div> \ No newline at end of file diff --git a/input/en-us/community-repository/moderation/package-verifier.md b/input/en-us/community-repository/moderation/package-verifier.md deleted file mode 100644 index 04ff686650..0000000000 --- a/input/en-us/community-repository/moderation/package-verifier.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -Order: 20 -xref: package-verifier-service -Title: Package Verifier Moderation Service -Description: Information on the Package Verifier Moderation Service ---- - -Here you will find a collection of more information and resources for when things fail verification. - -## What is the verifier? - -The verifier is a service that checks the correctness (that the package actually works), that it installs and uninstalls correctly, has the right dependencies to ensure it is installed properly and can be installed silently. The verifier runs against both submitted packages and existing packages (checking every two weeks that a package can still install and sending notice when it fails). We like to think of the verifier as integration testing. It’s testing all the parts and ensuring everything is good. On the [community feed](https://chocolatey.org), you can see the current status of a package based on a little colored ball next to the title. If the ball is green or red, the ball is a link to the results (only on the package page, not in the list screen). - -* Green means good. The ball is a link to the results -* Orange if still pending verification (has not yet run). -* Red means it failed verification for some reason. The ball is a link to the results. -* Grey means unknown or excluded from verification (if excluded, a reason will be listed on the package page). - -## Specifications - -> :choco-info: **NOTE** -> -> We currently run against only one system. This was chosen as it will install almost all Chocolatey packages. We will be adding multiple systems in the future. - -The systems we run against: -* Windows Server 2012 R2 x64 - * It's a completely stock machine, no Windows updates applied. No hotfixes. Imagine that you took the image and ran it without applying any Windows updates. - * Has very limited things installed (bitvise sshd, git, notepad++, 7zip) - * The Printer Spooler Service is stopped and disabled. This can cause problems for packages that deal with software that relates to anything to do with printing, i.e. printing of PDF files. - - -## How can I bypass the verifier? - -If your package needs to be exempted, please contact the site admins on the package page of the package that needs the bypass. - -## How does the verifier work? - -### Prerequisites - -The verifier has the following prerequisites for it to work: - -* VirtualBox installed (4.3.x series - the verifier box has 4.3.28 installed) -* Vagrant installed (right now 1.7.4 is recommended) -* Vagrant sahara plugin installed -* Vagrant box `win2012r2x64` available -* A Windows machine that can run 64bit virtual boxes. Usually a physical machine can do this. Others require vt-x - -### What the verifier does at a high level - -1. Checks for packages ready to be tested. -1. Runs vagrant controlling a clean windows box to test. Limits the execution of the install/uninstall commands to 20 minutes each. -1. Submits the results to a GitHub gist. -1. Submits those results with pass/fail back to https://chocolatey.org. - -#### Vagrant Testing - -> :choco-info: **NOTE** -> -> You can repeat the testing of the verifier at https://github.com/chocolatey/chocolatey-test-environment - -##### Box Prep -* Copy `PrepareMachine.ps1` to `VagrantAction.ps1` -* Run `vagrant up` -* Run `vagrant sandbox on` - -##### Steps For Each Package -* Run `vagrant sandbox rollback` -* Copy `ChocolateyAction.ps1` to `VagrantAction.ps1` - replace `{{action}}` with `install`, `{{package}}`, and `{{version}}` and forcex86. -* Run `vagrant provision` - capture output (this is the install 32bit log), note the exit code. -* Copy `ChocolateyAction.ps1` to `VagrantAction.ps1` - replace `{{action}}` with `upgrade`, `{{package}}`, and `{{version}}` and forcex86. -* Run `vagrant provision` - capture output (this is the upgrade log), note the exit code. -* Run `vagrant sandbox rollback` -* Copy `ChocolateyAction.ps1` to `VagrantAction.ps1` - replace `{{action}}` with `install`, `{{package}}`, and `{{version}}`. -* Run `vagrant provision` - capture output (this is the install log), note the exit code. -* Copy `ChocolateyAction.ps1` to `VagrantAction.ps1` - replace `{{action}}` with `uninstall`, `{{package}}`, and `{{version}}`. -* Run `vagrant provision` - capture output (this is the uninstall log), note the exit code. -* Run `vagrant sandbox rollback` to set the machine ready. diff --git a/input/en-us/community-repository/script-builder.md b/input/en-us/community-repository/script-builder.md deleted file mode 100644 index 7625da09c5..0000000000 --- a/input/en-us/community-repository/script-builder.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -Order: 25 -xref: script-builder -Title: Script Builder -Description: Features and benefits of Script Builder ---- - -Script Builder allows you to bulk install Chocolatey packages in just a few clicks by providing clear, step-by-step instructions, on how to get packages into your environment quickly and easily using generated scripts. Just add packages to the builder and choose your integration method to get started. - -> :choco-info: **NOTE** -> -> Packages selected in Script Builder, the [internal repository url](#internal-repository-url) provided, and your selected integration method are saved within the browser on your computer and will not be available on other computers. - -## Adding and removing packages - -> :choco-info: **NOTE** -> -> Package versions are always included in generated scripts. In a future release, a toggle will be provided to remove version numbers. - -Packages can be added or removed from Script Builder virtually anywhere: - -1. From the main list of packages. - ![Add package from list of packages](/assets/images/script-builder/sb-add-list.jpg) - -1. From the individual package page. - ![Add package from the package details page](/assets/images/script-builder/sb-add-package-page.jpg) - -1. And even from the version history table on the individual package page. Multiple versions of the same package cannot be added to Script Builder. - ![Add package from the version history table](/assets/images/script-builder/sb-add-version.jpg) - -## Specifics for Individual Use - -When using Script Builder for individual use, follow these steps: - -1. Review your packages. -1. Verify your chosen integration method. -1. Choose to copy the installation script or download as a `.config` file. - -![Script Builder individual use](/assets/images/script-builder/sb-individual.gif) - -## Specifics for Organizational Use - -> :choco-warning: **WARNING** -> -> The organizational use of the Chocolatey Community Repository is not recommended. Please see how to setup [Chocolatey for internal / organizational use](xref:organizational-deployment-guide). - -When using Script Builder for an organization, follow these steps: - -1. Review your packages. -1. Verify your chosen [integration method](#integration-methods). Choose from a generic PowerShell, Ansible, Chef, PowerShell DSC, or Puppet script. -1. Enter your [internal repository url](#internal-repository-url). -1. Get the [packages into your environment](#environment-setup). -1. Copy the installation scripts and configuration scripts. - -![Script Builder organizational use](/assets/images/script-builder/sb-organization.gif) - -### Integration Methods - -Currently, Script Builder provides installation and configuration scripts as a generic PowerShell script as well as Ansible, Chef, PowerShell DSC, and Puppet. - -### Internal Repository Url - -The Internal Repository Url is the location of your internal package repository. Read over [How To Set Up an Internal Repository](xref:host-packages) for options and more information on using Artifactory Pro, Nexus, and ProGet. - -> :choco-danger: **IMPORTANT** -> -> An Internal Repository Url is required and you will not be able to proceed with further steps in Script Builder until one is supplied. - -![Internal Repository Url](/assets/images/script-builder/sb-internal-url.jpg) - -### Environment Setup - -Script Builder provides the instructions on how to get your selected packages into your specific environment. - -> :choco-info: **NOTE** -> -> When choosing to bulk download packages from this step, your browser may block multiple pop-ups, resulting in only 1 package being downloaded. To avoid this, be sure to add community.chocolatey.org to your list of approved sites to allow pop-ups and redirects. - -## We want your feedback! - -Have you found an issue or wish there was a specific feature included in Script Builder? Help us out and [file an issue on GitHub](https://github.com/chocolatey/home/issues). \ No newline at end of file diff --git a/input/en-us/community-repository/users/index.md b/input/en-us/community-repository/users/index.md deleted file mode 100644 index 94ce758465..0000000000 --- a/input/en-us/community-repository/users/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -Order: 30 -xref: users -Title: Users -Description: Information for the consumers of packages from the Chocolatey Community Repository ---- - -If you are a user of, or a consumer of packages from, the Chocolatey Community Repository, then the information below will help you understand more about the repository, the packages available and the processes we use. \ No newline at end of file diff --git a/input/en-us/community-repository/users/package-request.md b/input/en-us/community-repository/users/package-request.md deleted file mode 100644 index cea1b80e4d..0000000000 --- a/input/en-us/community-repository/users/package-request.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -Order: 40 -xref: package-request -Title: How To Request a New Package -Description: How to request a new package for the Chocolatey Community Repository. ---- - -If you are looking for a package to be added to the [Chocolatey Community Repository](https://community.chocolatey.org/packages) then there are a few options. - -### I Want To Create a Package For the Chocolatey Community Repository - -It's easy to [create and maintain packages](xref:create-packages). - -### I Want Somebody Else To Create a Package For the Chocolatey Community Repository - -> :choco-info: **NOTE** -> -> A few things to note: -> -> * Chocolatey Software does not create or maintain packages on the Chocolatey Community Repository. -> * Many members of the Chocolatey Team are also long-term members of the Chocolatey Community and maintain packages in their own time. -> * Packages on the Chocolatey Community Repository are created and maintained by volunteer Maintainers in their spare time, or by [Software Vendors or Authors](xref:software-vendor). -> * There is no obligation on _any_ Maintainer to pick up the package request and create a package. -> * The best way to get the package you want, is to [join the Community, to create and maintain it yourself](xref:create-packages). - -When it comes to community packages, we really want packages to be created by those who are using the software. So when you are asking for others to add packages, please consider that it may be better for you to keep the package up to date than someone else who may not be invested in ensuring it stays updated. - -Raise a **Request For Package (RFP)** request on the [Chocolatey Package Requests](https://github.com/chocolatey/chocolatey-package-requests) repository. A Repository Administrator will review the request and make it available for Maintainers to pick up. diff --git a/input/en-us/community-repository/users/package-triage-process.md b/input/en-us/community-repository/users/package-triage-process.md deleted file mode 100644 index 215e134522..0000000000 --- a/input/en-us/community-repository/users/package-triage-process.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -Order: 20 -xref: package-triage-process -Title: Package Triage Process -Description: The package triage process for Chocolatey Community Repository packages. -RedirectFrom: docs/package-triage-process ---- - -The [Chocolatey Community Repository](https://community.chocolatey.org/packages) has a collection of packages provided and maintained by the Community. You may have come across a package and found you have questions, or you have found it outdated or broken. You will find help with this below. - -> :choco-info: **NOTE** -> -> If you are a **Software Vendor/Author** wanting to maintain your software's packages, please see the [Software Vendor/Author information on the Chocolatey Community Repository](xref:software-vendor). - -## Package Is Outdated? - -Be sure of: - -1. If the package contains stable releases, the newer version is a stable release and not a prerelease (such as alpha or beta). -1. The newer version that is available, is for Windows. Sometimes the release of the Windows version may lag behind availability on other platforms. -1. Check the description on the package page of the [Chocolatey Community Repository](https://community.chocolatey.org/packages) for a timescale of when to contact the maintainer for outdated packages. Many maintainers add this information there. If there is no timescale, ensure it has been at least 2 days since the new release. -1. The [package doesn't already have a newer version in moderation](xref:ccr-faq#how-do-i-see-all-versions-of-a-package). The maintainer(s) may already be actively working towards getting a newer version up on the Chocolatey Community Repository. - -If you are sure of the above list, please follow the [Package Triage Process](#the-triage-process). - -## Package is Broken? - -![red ball failing testing verification](/assets/images/triage-broken.jpg) - -If the ball is red, the maintainer has already been informed. - -Package maintainers are unlikely to provide fixes to versions of packages that are not the latest. If the broken package is the [latest available](xref:ccr-faq#how-do-i-see-all-versions-of-a-package), please follow the [Package Triage Process](#the-triage-process). - -## The Triage Process - -> :choco-info: **WARNING** -> -> If the maintainer of the package is in the list below, you do not need to follow these steps. Instead, please contact the [Site Admins](xref:ccr-faq#how-do-i-contact-the-site-admins) if you wish to become the Maintainer of the package, or raise a [Request For Maintainer (RFM) package request](xref:package-request) if you do not. -> -> * needs_new_maintainer -> * dtgm -> * adgellida - -If a package needs to be fixed or updated. Here are the steps to follow: - -1. The first steps are: - 1. [Contact the package Maintainers](xref:ccr-faq#how-do-i-contact-the-package-maintainers). - 1. Find the [package source](xref:ccr-faq#how-do-i-find-the-package-source) and if it is a source code repository: - * [Raise a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) if the repository allows it, and the package is broken, and you want to help fix it. - * [Raise an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue) if the repository allows it, and you want to report the package as broken or outdated. - * [Ask a question about the package](xref:ccr-faq#how-do-i-ask-questions-about-a-package). -1. Wait 7 days for a response from the Maintainers. -1. If the Maintainers have not responded, there are two options: - 1. If you wish to become a Maintainer of the package, please [contact the Site Admins](xref:ccr-faq#how-do-i-contact-the-site-admins). The Site Admins will follow up with you directly. If the Site Admins add you as a Maintainer of the package, see the [Package Maintainer Handover/Switch](xref:package-maintainer-handover) documentation for more information. - 1. If you do not wish to become a Maintainer of the package, please raise a [Request For Maintainer (RFM) package request](xref:package-request), including how you contacted the existing Maintainers, links to any issues, discussions or pull requests you raised, and the dates when this contact was initiated. The Repository Administrators will review the request. - -### Package Request? Package Missing? - -See the [FAQ question](xref:package-request). - -### Questions About a Package or Software - -See the [FAQ question](xref:ccr-faq#how-do-i-ask-questions-about-a-package). - -### Are You A Software Vendor? - -See the documentation page for [Software Vendor/Authors](xref:software-vendor).. \ No newline at end of file diff --git a/input/en-us/community-repository/users/software-vendor.md b/input/en-us/community-repository/users/software-vendor.md deleted file mode 100644 index cfa64a10d3..0000000000 --- a/input/en-us/community-repository/users/software-vendor.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -Order: 10 -xref: software-vendor -Title: Software Vendors/Authors -Description: Software Vendor/Author information on the Chocolatey Community Repository. -RedirectFrom: community-repository/users/package-triage-process#are-you-a-software-vendor ---- - -If you are a Software Vendor or Author, then the information below will help answer some questions you may have on the Chocolatey Community Repository, how it works and how your software is being installed by packages. - -## How Do I Inspect the Contents Of a Chocolatey Package? - -See the [FAQ question](xref:ccr-faq#how-do-i-inspect-the-contents-of-a-chocolatey-package). - -## Does a Chocolatey Community Repository Package Violate Distribution Rights If It Installs My Software? - -In most cases, no. Most packages you will find on the [Chocolatey Community Repository](https://community.chocolatey.org/packages) use automation scripts to download the software from the [official distribution point](xref:legal#distributions). - -If you visit the package page you can view the [files included with the package, or download the actual package, to inspect its contents](xref:ccr-faq#how-do-i-inspect-the-contents-of-a-chocolatey-package). - -Many of the packages may look like they include files because of the result after an installation, but that's just a fantastic effect of the automation scripts working smoothly and almost unnoticeably. - -[We take distribution rights very seriously](xref:legal#distributions). If you determine that the package **is** violating your distribution rights, please see [here](#the-package-is-violating-distribution-rights). - -## The Package Is Violating Distribution Rights - -> :choco-info: **NOTE** -> -> The Chocolatey Community Repository has only been moderated since October 2014. There may be some packages created prior to this date that could violate distribution rights. These packages won't likely list the files as the Chocolatey Community Repository did not start capturing them until July 2014. If you visit the package page you can view the [files included with the package, or download the actual package, to inspect its contents](xref:ccr-faq#how-do-i-inspect-the-contents-of-a-chocolatey-package). - -You've checked the previous section, and it doesn't apply, and you've found that the package **is** violating distribution rights as it bundles software without your permission and/or the license doesn't allow for it. - -It's not often that a Moderator would approve a package that violates distribution rights, but if you find one, please [fill out and submit the abuse form](xref:ccr-faq#how-to-report-an-abusive-package). The Site Administrators will follow up with you. - -## I Want To Take Over/Help With Package Maintenance For My Software - -1. The first step is to [contact the Maintainers](xref:ccr-faq#how-do-i-contact-the-package-maintainers) to explain you are the Software Vendor/Author, that you would like to help or take over package maintenance, and request that they add you as a Maintainer. Maintainers have put a lot of time and effort into maintaining the package that installs your software, so we ask Software Vendors/Authors to respect this, and first contact them. - -1. If the Maintainers do not respond after 7 days, or if they do not add you as a Maintainer, [contact the Site Admins](xref:ccr-faq#how-do-i-contact-the-site-admins). Please include details of how and when you attempted to contact the Maintainers, and that you are the Software Vendor/Author of the software. - -1. Wait for a response from the Site Administrators. Once you have been added as a Maintainer of the package, please follow the instructions for a [Package Maintainer Handover/Switch](xref:package-maintainer-handover) for how to start maintaining the package. - -## I Have Other Questions Not Answered Here - -If you have other questions, please [contact the Site Admins](xref:ccr-faq#how-do-i-contact-the-site-admins). diff --git a/input/en-us/configuration.md b/input/en-us/configuration.md deleted file mode 100644 index 3fd6b8de9e..0000000000 --- a/input/en-us/configuration.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -Order: 60 -xref: configuration -Title: Configuration -Description: Information on the different configuration options for Chocolatey -RedirectFrom: docs/chocolatey-configuration ---- - -There are settings and features that can customize the way that Chocolatey works for you. The following is a list of config settings and features and their default values. - -> :choco-info: **NOTE** -> -> When a Chocolatey configuration or feature is removed (for example, it becomes deprecated and no longer required), it will not be removed from the chocolatey.config file automatically when you upgrade Chocolatey. -> This is in order to preserve backwards compatibility, should the user decide to go back to a previous version of Chocolatey. - -## Config Settings - -Config settings are adjusted using `choco config set --name="'<nameFromBelow>'" --value="'<value>'"` and set back to default with `choco config unset --name="'<nameFromBelow>'"`. For more information see [`choco config` command](xref:choco-command-config) or run `choco config -?`. - -### General - -* `cacheLocation` = **' '** - Cache location if not TEMP folder. Replaces `$env:TEMP` value. It is highly recommended this be set to make Chocolatey more deterministic in cleanup. -* `upgradeAllExceptions` = **' '** - A comma-separated list of package names that should not be upgraded when running `choco upgrade all'. Defaults to empty. -* `defaultTemplateName` = **' '** - Default template name used when running [`choco new` command](xref:choco-command-new). -* `defaultPushSource` = **' '** - Default source to push packages to when running [`choco push` command](xref:choco-command-push). - -### Proxy - -* `proxy` = **' '** - Explicit proxy location. -* `proxyUser` = **' '** - Optional proxy user. Requires explicit proxy configured. -* `proxyPassword` = **' '** - Optional proxy password. Encrypted. Requires explicit proxy and proxyUser configured. -* `proxyBypassList` = **' '** - Optional regex proxy bypass list. Comma separated. Requires explicit proxy configured. -* `proxyBypassOnLocal` = **'true'** - Bypass proxy for local connections. Requires explicit proxy configured. - -### Timeouts - -* `commandExecutionTimeoutSeconds` = **'2700'** - Default timeout for command execution. '0' for infinite. It is recommended that organizations bump this up to at least 4 hours (14400). -* `webRequestTimeoutSeconds` = **'30'** - Default timeout for web requests. - -### Other - -* `containsLegacyPackageInstalls` = **'true'** - Install has packages installed prior to 0.9.9 series. - -## Config Settings - Licensed Edition - -### Chocolatey Central Management - -* `centralManagementServiceUrl` = **' '** - The URL that should be used to communicate with Chocolatey Central Management. It should look something like `https://servicemachineFQDN:24020/ChocolateyManagementService`. See <https://docs.chocolatey.org/en-us/features/chocolatey-central-management#fqdn-usage>. Available in business editions only. -* `centralManagementReportPackagesTimerIntervalInSeconds` = **'1800'** - Amount of time, in seconds, between each execution of the background service to report installed and outdated packages to Chocolatey Central Management. Available in business editions only. -* `centralManagementReceiveTimeoutInSeconds` = **'30'** - The amount of time, in seconds, that the background agent should wait to receive information from Chocolatey Central Management. Available in business editions only. -* `centralManagementSendTimeoutInSeconds` = **'30'** - The amount of time, in seconds, that the background agent should wait to send information to Chocolatey Central Management. Available in business editions only. -* `centralManagementCertificateValidationMode` = **'PeerOrChainTrust'** - The certificate mode that is used in communication to Chocolatey Central Management. Available in business editions only. -* `centralManagementMaxReceiveMessageSizeInBytes` = **'2147483647'** - The size of the permitted message, in bytes, which can be exchanged between the Chocolatey Background Agent and Chocolatey Central Management. Available in business editions only. -* `centralManagementDeploymentCheckTimerIntervalInSeconds` = **'180'** - Amount of time, in seconds, between each execution of the Chocolatey Agent service to check for a new Deployment Step from Chocolatey Central Management. Available in business editions only. -* `centralManagementClientCommunicationSaltAdditivePassword` = **' '** - Chocolatey Central Management Client Communication Salt Additive - The salt additive to use in the salt recipe for encrypting and verifying communication from an agent TO an instance of Central Management Service (will need to be set the same on all clients contacting that service AND the instance of the management service itself). When not set a default encryption phrase set by the system will be used. When set the unencrypted value must match exactly with what is set in the configuration for Central Management Service and every client contacting that instance of Central Management Service. Value is not shared over the wire. Because this is a much more involved process, it is recommended only setting this if you are transmitting messages over the internet. Defaults to ''. Needs to be at least 8 characters long if set or it will throw errors and use the default. Available in business editions only. -* `centralManagementServiceCommunicationSaltAdditivePassword` = **' '** - Chocolatey Central Management Communication Salt Additive - The salt additive to use in the salt recipe for encrypting and verifying communication FROM an instance of Central Management Service to an agent (will need to be set the same on all clients contacting that service AND the instance of the management service itself). When not set a default encryption phrase set by the system will be used. When set the unencrypted value must match exactly with what is set in the configuration for Central Management Service and every client contacting that instance of Central Management Service. Value is not shared over the wire. Because this is a much more involved process, it is recommended only setting this if you are transmitting messages over the internet. Defaults to ''. Needs to be at least 8 characters long if set or it will throw errors and use the default. Available in business editions only. - -### Intune - -* `intuneTenantGUID` = **' '** - The tenant to use by default when no `--source` argument is used on the `push` command. The GUID is available on the [Azure AD Application page](https://aad.portal.azure.com/). Available in business editions only. -* `intuneAuthenticationUrl` = **'https://login.microsoftonline.com'** - The URL used when authenticating to the Microsoft Intune API. _Only change this if you know what you are doing_. Available in business editions only. -* `intuneApiUrl` = **'https://graph.microsoft.com'** - The URL used when handling requests to the Intune API, for instance, when checking for available packages on Intune. _Only change this if you know what you are doing_. Available in business editions only. -* `intuneRetryIntervalInSeconds` = **'5'** - The amount of time, in seconds, that Chocolatey should wait before retrying any calls to the Intune API. Available in business editions only. -* `intuneUploadTimeoutInSeconds` = **'600'** - The amount of time, in seconds, that Chocolatey should wait for completion while uploading files to Intune. Available in business editions only.. -* `intuneUploadChunkSizeInMegabytes` = **'10'** - The size of the file, in megabytes, below which Chocolatey will split the upload into multiple chunks. Above this size, Chocolatey will make a best effort to break the upload into logical chunk sizes. Available in business editions only. - -### Package Throttle - -* `maximumDownloadRateBitsPerSecond` = **' '** - The maximum download rate in bits per second. '0' or empty means no maximum. A number means that will be the maximum download rate in bps. Defaults to ''. Available in licensed editions only. See <https://docs.chocolatey.org/en-us/features/package-throttle> - -### Windows Services Installation - -* `serviceInstallsDefaultUserName` = **'ChocolateyLocalAdmin'** - The default user name to use for installing services when one is not specified. Defaults to 'ChocolateyLocalAdmin'. The feature 'useLocalSystemForServiceInstalls' must be set to 'false' to use this field. Available in business editions only. -* `serviceInstallsDefaultUserPassword` = **' '** - The default user password to use for installing services when one is not specified. Defaults to ''. When '', the value will be generated as encrypted hash specific to the machine and will not be known. The feature 'useLocalSystemForServiceInstalls' must be set to 'false' to use this field. Available in business editions only. - -### Self-Service / Background Mode - -* `backgroundServiceAllowedCommands` = **'install,upgrade'** - Background Service Allowed Commands - The different commands that will direct through the background service separated with comma or semi-colon. Supported across all operational commands, not supported with commands that change configuration (config, source, feature, apikey, etc). Defaults to 'install,upgrade'. Available in business editions only. -* `logRetentionPolicyInDays` = **'30'** - The maximum age in days before a rollover log file should be cleaned up. Invalid values or a value of '0' or below is equal to the default value of '30' days. - -### Virus Checking - -* `virusCheckMinimumPositives` = **'4'** - Minimum number of scan result positives before flagging a binary as a possible virus. Used when virusScannerType is VirusTotal. Licensed editions only. See <https://docs.chocolatey.org/en-us/features/virus-check> -* `virusScannerType` = **'VirusTotal'** - Virus Scanner Type (Generic or VirusTotal). Defaults to VirusTotal for Pro. Licensed editions only. See <https://docs.chocolatey.org/en-us/features/virus-check> -* `genericVirusScannerPath` = **' '** - The full path to the command line virus scanner executable. Used when virusScannerType is Generic. Licensed editions only. See <https://docs.chocolatey.org/en-us/features/virus-check> -* `genericVirusScannerArgs` = **'`[[File]]`'** - The arguments to pass to the generic virus scanner. Use `[[File]]` for the file path placeholder. Used when virusScannerType is Generic. Licensed editions only. See <https://docs.chocolatey.org/en-us/features/virus-check> -* `genericVirusScannerValidExitCodes` = **'0'** - The exit codes for the generic virus scanner when a file is not flagged. Separate with comma, defaults to 0. Used when virusScannerType is Generic. Licensed editions only. See <https://docs.chocolatey.org/en-us/features/virus-check> -* `genericVirusScannerTimeoutInSeconds` = **'120'** - Generic Virus Scanner Timeout In Seconds - The number of seconds to allow the virus scanner to run before timing out. Used when virusScannerType is Generic. Defaults to '120'. Licensed editions v2.1.0+ only. See <https://docs.chocolatey.org/en-us/features/virus-check> - -## Features - -Features are adjusted using `choco feature enable|disable --name="'<nameFromBelow>'"`. For more information see [`choco feature` command](xref:choco-command-feature) or run `choco feature -?`. - -A checkbox means this feature is turned on by default. - -### General - -* [ ] `logWithoutColor` - Log without color - Do not show colorization in logging output. -* [ ] `logEnvironmentValues` - Log Environment Values - will log values of environment before and after install (could disclose sensitive data). -* [x] `showNonElevatedWarnings` - Show Non-Elevated Warnings - Display non-elevated warnings. -* [x] `showDownloadProgress` - Show Download Progress - Show download progress percentages in the CLI. -* [ ] `useRememberedArgumentsForUpgrades` - Use Remembered Arguments For Upgrades - when running upgrades, use arguments for upgrade that were used for installation ('remembered'). This is helpful when running upgrade for all packages. This is considered in preview and will be flipped to on by default in a future release. -* [ ] `logValidationResultsOnWarnings` - Log validation results on warnings - Should the validation results be logged if there are warnings? - -### Automatic Uninstaller - -* [x] `autoUninstaller` - Uninstall from programs and features without requiring an explicit uninstall script. -* [ ] `failOnAutoUninstaller` - Fail if automatic uninstaller fails. - -### Exit Codes - -* [x] `usePackageExitCodes` - Use Package Exit Codes - Package scripts can provide exit codes. With this on, package exit codes will be what choco uses for exit when non-zero (this value can come from a dependency package). Chocolatey defines valid exit codes as 0, 1605, 1614, 1641, 3010. With this feature off, choco will exit with 0, 1, or -1 (matching previous behavior). -* [ ] `useEnhancedExitCodes` - Use Enhanced Exit Codes - Chocolatey is able to provide enhanced exit codes surrounding list, search, info, outdated and other commands that don't deal directly with package operations. To see enhanced exit codes and their meanings, please run `choco [cmdname] -?`. With this feature off, choco will exit with 0, 1, or -1 (matching previous behavior). Default off. -* [ ] `exitOnRebootDetected` - Exit On Reboot Detected - Stop running install, upgrade, or uninstall when a reboot request is detected. Requires 'usePackageExitCodes' feature to be turned on. Will exit with either 350 or 1604. When it exits with 350, it means pending reboot discovered prior to running operation. When it exits with 1604, it means some work completed prior to reboot request being detected. - -### Flow Control - -* [x] `ignoreInvalidOptionsSwitches` - Ignore Invalid Options/Switches - If a switch or option is passed that is not recognized, should choco fail? -* [ ] `failOnStandardError` - Fail if install provider writes to stderr. Not recommended for use. -* [ ] `stopOnFirstPackageFailure` - Stop On First Package Failure - stop running install, upgrade or uninstall on first package failure instead of continuing with others. As this will affect upgrade all, it is normally recommended to leave this off. -* [ ] `skipPackageUpgradesWhenNotInstalled` - Skip Packages Not Installed During Upgrade - if a package is not installed, do not install it during the upgrade process. -* [ ] `ignoreUnfoundPackagesOnUpgradeOutdated` - Ignore Unfound Packages On Upgrade Outdated - When checking outdated or upgrades, if a package is not found against sources specified, don't report the package at all. -* [x] `usePackageRepositoryOptimizations` - Turn on optimizations for reducing bandwidth with repository queries during package install/upgrade/outdated operations. Should generally be left enabled, unless a repository needs to support older methods of query. When disabled, this makes queries similar to the way they were done in Chocolatey v0.10.11 and before. - -### Security - -* [ ] `useFipsCompliantChecksums` - Use FIPS Compliant Checksums - Ensure checksumming done by choco uses FIPS compliant algorithms. Not recommended unless required by FIPS Mode. Enabling on an existing installation could have unintended consequences related to upgrades/uninstalls. -* [x] `checksumFiles` - Checksum files when pulled in from internet (based on package). -* [ ] `allowEmptyChecksums` - Allow packages to have empty/missing checksums for downloaded resources from non-secure locations (HTTP, FTP). Enabling is not recommended if using sources that download resources from the internet. -* [x] `allowEmptyChecksumsSecure` - Allow packages to have empty/missing checksums for downloaded resources from secure locations (HTTPS). -* [ ] `allowGlobalConfirmation` - Prompt for confirmation in scripts or bypass. -* [ ] `usePackageHashValidation` - Check the hash of the downloaded package file against the source provided hash. Only supports sources that provide SHA512 hashes. Available in 2.3.0+. - -### Other - -* [x] `powershellHost` - Use Chocolatey's built-in PowerShell host. -* [ ] `removePackageInformationOnUninstall` - Remove Stored Package Information On Uninstall - When a package is uninstalled, should the stored package information also be removed? -* [ ] `disableCompatibilityChecks` - Disable Compatibility Checks - Disable showing a warning when there is an incompatibility between Chocolatey CLI and Chocolatey Licensed Extension. Available in 1.1.0+. - -## Features - Licensed Edition - -### General - -* [x] `downloadCache` - Download Cache - use the private download cache if available for a package. Licensed editions only. See <https://docs.chocolatey.org/en-us/features/private-cdn> -* [ ] `failOnInvalidOrMissingLicense` - Fail On Invalid Or Missing License - allows knowing when a license is expired or not applied to a machine. -* [x] `warnOnUpcomingLicenseExpiration` - Warn On Upcoming License Expiration - When a license expiration date is upcoming, should Chocolatey provide a warning? MSP and Business editions only. Setting ignored in trial editions. -* [ ] `excludeChocolateyPackagesDuringUpgradeAll` - Exclude Chocolatey Packages During Upgrade All - When enabled, all official Chocolatey packages will be added to the comma-separated list of package names that should not be upgraded when upgrading 'all'. Any packages specified in the 'upgradeAllExceptions' configuration setting will still be respected. Licensed editions only (version 4.1.0+). - -### Access Control / Security - -* [ ] `adminOnlyExecutionForAllChocolateyCommands` - Limit to Administrator Execution Only for All Chocolatey Commands - If enabled, only administrators will be able to run 'choco' commands. Business editions only. -* [ ] `adminOnlyExecutionForNewCommand` - Limit to Administrator Execution Only for New Command - If enabled, only administrators will be able to run 'choco new'. Business editions only. -* [ ] `adminOnlyExecutionForDownloadCommand` - Limit to Administrator Execution Only for Download Command - If enabled, only administrators will be able to run 'choco download'. Business editions only. -* [x] `useLocalSystemForServiceInstalls` - Use LocalSystem For Service Installs - When installing services that don't indicate a user/password, use the LocalSystem for those installations. When turned off, Chocolatey will manage a local admin with a password unique to the machine but will never know it. Business editions only. - -### Chocolatey Central Management - -* [ ] `useChocolateyCentralManagement` - Use Chocolatey Central Management - Lists of installed and outdated packages will be reported to the chosen Chocolatey Central Management server. Business editions only. See <https://docs.chocolatey.org/en-us/features/chocolatey-central-management> -* [ ] `useChocolateyCentralManagementDeployments` - Use Chocolatey Central Management Deployments - Centrally managed deployments of packages and scripts can be sent from Chocolatey Central Management. Business editions only (version 2.1.0+). See <https://docs.chocolatey.org/en-us/features/chocolatey-central-management> - -### Package Internalizer - -* [x] `internalizeAppendUseOriginalLocation` - Append UseOriginalLocation with Package Internalizer - When `Install-ChocolateyPackage` is internalized, append the `-UseOriginalLocation` parameter to the function. Business editions and MSP editions only. See <https://docs.chocolatey.org/en-us/guides/create/recompile-packages> - -### Package Reducer - -* [x] `reduceInstalledPackageSpaceUsage` - Reduce Installed Package Size (Package Reducer) - Reduce size of the nupkg file to very small and remove extracted archives and installers. Licensed editions only. See <https://docs.chocolatey.org/en-us/features/package-reducer> -* [ ] `reduceOnlyNupkgSize` - Reduce Only Nupkg File Size - reduce only the size of nupkg file when using Package Reducer. Licensed editions only. Also requires 'reduceInstalledPackageSpaceUsage' to be enabled. See <https://docs.chocolatey.org/en-us/features/package-reducer> - -### Package Synchronization - -* [x] `allowSynchronization` - Synchronization - Keep installed Chocolatey packages in sync with changes in Programs and Features. Licensed editions only. See <https://docs.chocolatey.org/en-us/features/package-synchronization> -* [ ] `showAllPackagesInProgramsAndFeatures` - Package Synchronizer's Packages In Programs And Features Synchronization - Show all packages in Programs and Features, not just packages that use a native installer. Business editions only. - -### Self-Service / Background Mode - -* [x] `useBackgroundService` - Use Background Service (Self-Service Installer) - For some commands like install and upgrade, use a background service instead of running the command directly. Business editions only. Requires the package chocolatey-agent (choco install chocolatey-agent). See <https://docs.chocolatey.org/en-us/features/self-service-anywhere> -* [x] `useBackgroundServiceWithSelfServiceSourcesOnly` - Use Background Service With Self-Service Sources Only - When using Self-Service, opt-in only sources configured to be used with self-service. This allows for other sources only an admin can use. Business editions only. -* [x] `useBackgroundServiceWithNonAdministratorsOnly` - Use Background Service With Non-Administrators Only - When using Self-Service, only execute background mode for non-administrators. Business editions only. -* [ ] `useBackgroundServiceInteractively` - Use Background Service Interactively (BROKEN CURRENTLY - DO NOT USE) - When using Self-Service and installing software that cannot be completely silent, installs will need to be executed against the current desktop environment. Set this flag on for the most compatibility. To use this feature, you must be using the local 'ChocolateyLocalAdmin' account. Business editions only. -* [x] `useBackgroundServiceWithEmptySessions` - Use Background Service With Empty Sessions - Sometimes empty sessions mean remotely run sessions, but in in newer Windows it is much more normal to see empty sessions with interactive use. Leave this flag on unless you absolutely need it off (control how remote sessions use background service by enabling the feature 'useBackgroundServiceWithNonAdministratorsOnly'). Business editions only. -* [ ] `allowBackgroundServiceUninstallsFromUserInstallsOnly` - Allow ONLY Uninstall of Packages Installed By a Self-service User in Background Service - Allow a user to uninstall packages they've installed - they must be reported as the original user in a choco list --audit. The config setting 'backgroundServiceAllowedCommands' must must have 'uninstall' added as well for this to work. Business editions only. -* [ ] `allowBackgroundServiceOverride` - Allows a user to request using the self-service when they are running the commands that can be run through the background service. Licensed editions only (version 5.0.0+). -* [x] `useLogRetentionPolicy` - Use Automatic Log Retention Policy - Once per day, remove any log files that are older than the `logRetentionPolicyInDays` value. Licensed editions only (version 5.0.0+). - -### Virus Checking - -* [x] `virusCheck` - Virus Check - perform virus checking on downloaded files. Licensed editions only. See <https://docs.chocolatey.org/en-us/features/virus-check> - -### Other - -* [x] `allowPreviewFeatures` - Allow Preview Features - Turns on Preview Features. Some features become available for preview before they are released for testing purposes. Please note these should not be used for production systems as they could mess up a system. Licensed editions only. diff --git a/input/en-us/create/automatic-packages.md b/input/en-us/create/automatic-packages.md deleted file mode 100644 index f7ad3048c6..0000000000 --- a/input/en-us/create/automatic-packages.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -Order: 50 -xref: automatic-packaging -Title: Automatic Packaging -Description: Techniques for automatically updating Chocolatey packages when new version of application is released -RedirectFrom: docs/automatic-packages ---- - -Automatic packaging is a process that **package maintainers can run on *their own* to keep the packages they maintain up to date**. It is not a required step for maintaining packages on the community feed (https://community.chocolatey.org/packages), but it is recommended you find a way to automate the delivery of packages to the community feed when there are updates if you are going to maintain more than 5 packages and you are not the software vendor for the packages you maintain. - -> :choco-info: **NOTE** -> -> Not to be confused with the automatic package creation feature in [Chocolatey for Business](https://chocolatey.org/compare) - that feature creates packages directly from software installer files. This feature is for package maintenance of existing packages on the community feed. - -## Automatic update methods - -There are currently two methods that can be used to maintain automatic packages: - -- RECOMMENDED - Using only PowerShell via [Chocolatey Automatic Package Updater Module](https://github.com/chocolatey-community/chocolatey-au). -- DEPRECATED - Using [Chocolatey Package Updater](https://community.chocolatey.org/packages/ChocolateyPackageUpdater) with 3rd party tool [Ketarin](https://community.chocolatey.org/packages/ketarin). - -## Automatic Updater (AU) - -The [Chocolatey Automatic Package Updater Module](https://github.com/chocolatey-community/chocolatey-au/blob/master/README.md) is a PowerShell module which implements functions that can be used to automate Chocolatey package updates. - -### Credits - -AU was created by Chocolatey community member [Miodrag Milic](https://github.com/majkinetor). -The original repository has been archived and is no longer receiving updates. - -Due to its widespread usage for many Chocolatey packages, we have forked the module into the [chocolatey-au](https://github.com/chocolatey-community/chocolatey-au) repository in the Chocolatey Community organisation where it will be maintained going forward. - -### Setup - -Follow the instructions at the [AU Wiki](https://github.com/majkinetor/au/wiki). - -When creating packages, do not use `--auto` as AU doesn't use token replacement for updating packages, it replaces the xml elements and code directly. - -## Chocolatey Package Updater aka chocopkgup [DEPRECATED] - -<a name="chocolatey-package-updater-aka-chocopkgup"></a> -http://community.chocolatey.org/packages/ChocolateyPackageUpdater - -The tool that accomplishes this process is known as [chocopkgup](https://community.chocolatey.org/packages/ChocolateyPackageUpdater) (Chocolatey Package Updater). It is a free tool (unless you want to use it for uploads to somewhere other than community.chocolatey.org). - -### Licensing - -Check the license at http://realdimensions.net/licenses/chocolateypackageupdater/license.txt to be sure that it applies to you. - -Basically it boils down to this: if you want to use chocopkgup privately, you will need to pay for it. As long as you are publishing to community.chocolatey.org, the tool is completely free! The license does expire every once in awhile, but if you are keeping up on your chocolatey updates locally, you won't even notice (`cup all`, remember?). - -### Credits - -This tool makes use of [Ketarin](https://community.chocolatey.org/packages/ketarin). Ketarin is an awesome tool that helps chocopkgup accomplish its tasks. - -### Requirements - -* A Windows box somewhere - to run the updater on -* [Ketarin](https://community.chocolatey.org/packages/ketarin) -* [Chocolatey Package Updater](https://community.chocolatey.org/packages/chocolateypackageupdater) - -### Setup - -1. Fork [`chocolatey-packages-template`](https://github.com/chocolatey/chocolatey-packages-template#fork-destination-box) and rename it to something like `chocolatey-packages` (on GitHub - go into Settings, Repository name and rename). -1. Clone the repo locally. -1. Install chocopkgup (which will install ketarin and nuget.commandline). `choco install chocolateypackageupdater`. -1. Check the config in `$env:ChocolateyInstall\lib\ChocolateyPackageUpdater\tools\chocopkgup\chocopkgup.exe.config`. The `PackagesFolder` key should point to where your repository is located. -1. Create a scheduled task (in Windows). This is the command (edit the path to `cmd.exe` accordingly): `C:\Windows\System32\cmd.exe /c c:\tools\chocolateypackageupdater\ketarinupdate.cmd` -1. Alternatively to stop the command window from opening on Windows, you can create a VBS script as well and put the path to the `.vbs` file instead of `ketarinupdate.cmd` as the command to run. The file should have the following: - - ~~~vb - Set objShell = WScript.CreateObject("WScript.Shell") - objShell.Run("C:\tools\ChocolateyPackageUpdater\ketarinupdate.cmd"), 0, True - ~~~ - -1. Choose a schedule for the task. Some folks run the task about once an hour to catch updates as quickly as they happen. -1. Open Ketarin. Choose `File` –> `Settings`. -1. Now Click Import... -1. Choose [setup/KetarinSettings.xml](https://github.com/chocolatey/chocolatey-packages-template/blob/master/setup/KetarinSettings.xml) from the repo folder. This is going to add everything in that you will need for settings. -1. Click on Global Variables. Ensure all of the variables are set appropriately. - - ![Ketarin Global Variables](/assets/images/chocopkgup/KetarinGlobalVariables.png) - -This gets Ketarin all set up with a global command for all packages we create. - -*NOTE*: This has set up global commands for "Before updating an application" and "After updating an application". Those should not need adjusting, however if you do, please be sure to export the settings again. - -### Create an Automatic Package - -Preferably you are taking an existing package that you have tested and converting it to an automatic package. - -#### Create a package for automatic packaging - -When you are creating packages, you should ensure you are on the latest version of Chocolatey. This means you have the latest fixes to packaging templates and latest and greatest in the way of automation. - -1. Ensuring you are on the latest version of Chocolatey - `choco upgrade chocolatey`. -1. Open PowerShell (or cmd.exe) and head to the automatic package folder you are using. This should be "repolocation\automatic". -1. Run `choco new <name> --auto [options]`. You can use a different package template if you have those installed - see [new command](xref:choco-command-new) for all options or run `choco new -?`. For package templates, see [how to create custom package templates](xref:create-custom-package-templates). -1. Inspect the output. Merge in your existing package logic if you have an existing package you are converting. -1. Ensure that `checksumType` and `checksumType64` is `sha256` as this is the type the updater will generate. -1. Make any adjustments you need to the package to prepare for packaging. - -#### Ketarin - -1. Open Ketarin. Choose `File` –> `Import…` -1. Choose [ketarin/_KetarinChocolateyTemplate.xml](https://github.com/chocolatey/chocolatey-packages-template/blob/master/ketarin/_KetarinChocolateyTemplate.xml) from the repo folder. -1. Answer the questions. This will create a new job for Ketarin to check. -1. One important thing to keep in mind is that **the name of the job needs to match the name of the package folder and nuspec *exactly*.** -1. Right click on that new job and select `Edit`. Take a look at the following: - - ![Ketarin Job Main](/assets/images/chocopkgup/KetarinMain.png "Ketarin Job Main") - -1. Click on `Variables` on the right of URL - - ![Ketarin Job Variables](/assets/images/chocopkgup/KetarinSetVariables.png "Ketarin Job Variables") - -1. On the left side you should see a variable for **version** and one for **url64**. Click on **version**. -1. Choose the appropriate method for you. Here I’ve chosen **Content from URL (start/end)**. -1. Enter the URL for versioning information. - - ![Ketarin Job Variables](/assets/images/chocopkgup/KetarinVariables.png "Ketarin Job Variables") - -1. In the contents itself, highlight enough good information before a version to be able to select it uniquely during updates (but not so much it doesn’t work every time as the page changes). Click on **Use selection as start**. -1. Now observe that it didn’t jump back too far. -1. Do the same with the ending part, keeping in mind that this side doesn’t need to be too much because it is found AFTER the start. Once selected click on **Use selection as end**. -1. It should look somewhat similar to have is presented in the picture above. -1. If you have a 64bit url you want to get, do the same for the url64 variable. -1. When all of this is good, click **OK**. -1. Click **OK** again. - -### Notes about tri-packages (meta/virtual aka *, *.install, and *.portable) - -**UPDATE AUG 2016:** This may no longer be true. Just set up three jobs. - -When you have the three packages, you should set up only two jobs, one for *.install and one for *.portable. - -In whichever job the meta package points to, you should add a command to that like you did for the settings for all jobs in ketarin. - -1. Click on the **Commands Tab** and set **Edit command for event** to “Before updating an application”. - - ![Ketarin Settings](/assets/images/chocopkgup/KetarinJobSettings.png "Ketarin Settings") - -1. Add the following text (replace `name` with the actual name of the meta package folder): - - ~~~cmd - chocopkgup /p name /v {version} /u "{preupdate-url}" /u64 "{url64}" /pp "{file}" /c "{Checksum}" /c64 "{Checksumx64}" - REM /disablepush - ~~~ - -1. Check the bottom of this section to be sure it set to **Command**. - - ![Ketarin Settings Command](/assets/images/chocopkgup/KetarinCustomCommand.png "Ketarin Settings Command") - -### Testing Ketarin/ChocoPkgUp: - -1. We need to get a good idea of whether this will work or not. -1. Open a command line and type `ketarin`. -1. Once Ketarin opens, open [global options](#setup) (steps 8 and 11), go to Global Variables and set `cscript` to `1` instead of `2` so that it only goes as far as creating packages. -1. Find your job, and right click -> Update. If everything is set good, in moments you will have a Chocolatey package in the folder you set under `{PackagesFolder}\_output`, where `{PackagesFolder}` is the path you set in the course of the [*Setup*](#setup) section of this article. -1. Inspect the resulting Chocolatey package(s) for any issues. -1. You should also test the scheduled task works appropriately. - -### Troubleshooting/Notes - -* Ketarin comes with a logging facility so you can see what it is doing. It’s under View –> Show Log. -* In the top level folder for chocopkgup (in program data), we log what we receive from Ketarin as well and the process of putting together a package. -* The name of the application in ketarin matches exactly that of the folder that is in the automatic packages folder. -* Every once in awhile you want to look in Ketarin to see what jobs might be failing. Then figure out why. -* Every once in awhile you will want to inspect the chocopkgupfolder to see if there are any packages that did not make it up for some reason or another and then upload them. -* If the downloaded application/installer has not changed, the package will not be generated. Delete the files in the download location specified in [*Ketarin*](#ketarin) and try again. - -### Important notes for files hosted on SourceForge - -Try this first: -* In advanced settings, ensure the user agent is `chocolatey command line`. This will allow ketarin to behave similarly to how Chocolatey does. - - ![Ketarin Job Advanced Settings](/assets/images/automatic-packages/ketarin-jobs-advanced-settings.png) - - It isn’t uncommon that certain SorceForge mirrors go offline or are extremely slow because of overload. Thus it is not recommended to use direct mirror links (e. g. `http://heanet.dl.sourceforge.net/project/…`) in your `chocolateyInstall.ps1` file, because this will frequently break your package and makes it unreliable. - To avoid this, use the following convention for files hosted on SourceForge: -* Don’t use `{{DownloadUrl}}` and `{{DownloadUrlx64}}` in your `chocolateyInstall.ps1` file, but use this instead (example of the app nomacs): -`$url = 'http://sourceforge.net/projects/nomacs/files/nomacs-{{PackageVersion}}/nomacs-setup-{{PackageVersion}}-x86.exe/download'` -and -`$url64 = 'http://sourceforge.net/projects/nomacs/files/nomacs-{{PackageVersion}}/nomacs-setup-{{PackageVersion}}-x64.exe/download'` -For other applications obviously you have to use the actual application/file names. Important is that you use `{{PackageVersion}}` and don’t use any direct links which include SourceForge mirrors. diff --git a/input/en-us/create/cmdlets/Get-EnvironmentVariable.md b/input/en-us/create/cmdlets/Get-EnvironmentVariable.md deleted file mode 100644 index f2cc3c2d34..0000000000 --- a/input/en-us/create/cmdlets/Get-EnvironmentVariable.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -Description: Information on Get-EnvironmentVariable cmdlet -external help file: Chocolatey.PowerShell.dll-Help.xml -Module Name: Chocolatey.PowerShell -online version: https://docs.chocolatey.org/en-us/create/functions/get-environmentvariable -Order: 70 -RedirectFrom: - - docs/helpers-get-environment-variable - - docs/helpersgetenvironmentvariable - - en-us/create/functions/get-environmentvariable -schema: 2.0.0 -Title: Get-EnvironmentVariable -xref: get-environmentvariable ---- - -# Get-EnvironmentVariable - -## SYNOPSIS -Gets an Environment Variable. - -## SYNTAX - -``` -Get-EnvironmentVariable [-Name] <String> [-Scope] <EnvironmentVariableTarget> [-PreserveVariables] - [-IgnoredArguments <Object[]>] [<CommonParameters>] -``` - -## DESCRIPTION -This will will get an environment variable based on the variable name and scope while accounting whether to expand the variable or not -(e.g.: `%TEMP%`-> `C:\User\Username\AppData\Local\Temp`). - -## EXAMPLES - -### Example 1 -```powershell -PS C:\> Get-EnvironmentVariable -Name 'TEMP' -Scope User -PreserveVariables -``` - -Gets the `TEMP` encironment variable from the user scope, without expanding embedded environment variables. - -### Example 2 -```powershell -PS C:\> Get-EnvironmentVariable -Name 'PATH' -Scope Machine -``` - -Gets the `PATH` environment variable from the machine scope, expanding embedded environment variables. - -## PARAMETERS - -### -IgnoredArguments -Allows splatting with arguments that do not apply. Do not use directly. - -```yaml -Type: Object[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Name -The environment variable you want to get the value from. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -PreserveVariables -Whether you want to expand embedded environment variable names or not. When not set, variables will be expanded. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Scope -The environment variable target scope. This is `Process`, `User`, or `Machine`. - -```yaml -Type: EnvironmentVariableTarget -Parameter Sets: (All) -Aliases: -Accepted values: Process, User, Machine - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -### System.String - -Outputs the value of the target environment variable as a string. - -## NOTES -This helper reduces the number of lines one would have to write to get environment variables, mainly when not expanding the variables is a must. - -## RELATED LINKS - -[Get-EnvironmentVariableNames](xref:get-environmentvariablenames) - -[Set-EnvironmentVariable](xref:set-environmentvariable) - -[Cmdlet Reference](xref:powershell-cmdlet-reference) - -[Function Reference](xref:powershell-reference) \ No newline at end of file diff --git a/input/en-us/create/cmdlets/Get-EnvironmentVariableNames.md b/input/en-us/create/cmdlets/Get-EnvironmentVariableNames.md deleted file mode 100644 index 374b0dc1c8..0000000000 --- a/input/en-us/create/cmdlets/Get-EnvironmentVariableNames.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -Description: Information on Get-EnvironmentVariableNames cmdlet -external help file: Chocolatey.PowerShell.dll-Help.xml -Module Name: Chocolatey.PowerShell -online version: https://docs.chocolatey.org/en-us/create/functions/get-environmentvariablenames -Order: 80 -RedirectFrom: - - docs/helpers-get-environment-variable-names - - docs/helpersgetenvironmentvariablenames - - en-us/create/functions/get-environmentvariablenames -schema: 2.0.0 -Title: Get-EnvironmentVariableNames -xref: get-environmentvariablenames ---- - -# Get-EnvironmentVariableNames - -## SYNOPSIS -Gets all environment variable names. - -## SYNTAX - -``` -Get-EnvironmentVariableNames [[-Scope] <EnvironmentVariableTarget>] [-IgnoredArguments <Object[]>] - [<CommonParameters>] -``` - -## DESCRIPTION -Provides a list of environment variable names based on the scope. This can be used to loop through the list and generate names. - -## EXAMPLES - -### Example 1 -```powershell -PS C:\> Get-EnvironmentVariableNames -Scope Machine -``` - -Outputs the names of all the environment variables defined in the registry for the Machine scope. - -## PARAMETERS - -### -IgnoredArguments -Allows splatting with arguments that do not apply. Do not use directly. - -```yaml -Type: Object[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Scope -The environment variable target scope. This is `Process`, `User`, or `Machine`. - -```yaml -Type: EnvironmentVariableTarget -Parameter Sets: (All) -Aliases: -Accepted values: Process, User, Machine - -Required: False -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -### System.String -Outputs the names of all the environment variables in the target scope as strings. - -## NOTES -Process dumps the current environment variable names in memory / session. The other scopes refer to the registry values. - -## RELATED LINKS - -[Get-EnvironmentVariable](xref:get-environmentvariable) - -[Set-EnvironmentVariable](xref:set-environmentvariable) - -[Cmdlet Reference](xref:powershell-cmdlet-reference) - -[Function Reference](xref:powershell-reference) \ No newline at end of file diff --git a/input/en-us/create/cmdlets/Install-ChocolateyPath.md b/input/en-us/create/cmdlets/Install-ChocolateyPath.md deleted file mode 100644 index 457fd02da2..0000000000 --- a/input/en-us/create/cmdlets/Install-ChocolateyPath.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -Description: Information on Install-ChocolateyPath cmdlet -external help file: Chocolatey.PowerShell.dll-Help.xml -Module Name: Chocolatey.PowerShell -online version: https://docs.chocolatey.org/en-us/create/functions/install-chocolateypath -Order: 250 -RedirectFrom: - - docs/helpers-install-chocolatey-path - - docs/helpersinstallchocolateypath - - en-us/create/functions/install-chocolateypath -schema: 2.0.0 -Title: Install-ChocolateyPath -xref: install-chocolateypath ---- - -# Install-ChocolateyPath - -## SYNOPSIS -> :choco-info: **NOTE** -> -> Administrative Access Required when `-PathType 'Machine'.` - -This puts a directory to the PATH environment variable. - -## SYNTAX - -``` -Install-ChocolateyPath [-Path] <String> [[-PathType] <EnvironmentVariableTarget>] - [-IgnoredArguments <Object[]>] [<CommonParameters>] -``` - -## DESCRIPTION -Looks at both PATH environment variables to ensure a path variable correctly shows up on the right PATH. - -## EXAMPLES - -### Example 2 -```powershell -PS C:\> Install-ChocolateyPath -PathToInstall "$($env:SystemDrive)\tools\gittfs" -``` - -Adds the target path to the current user's PATH. - -### Example 1 -```powershell -PS C:\> Install-ChocolateyPath "$($env:SystemDrive)\Program Files\MySQL\MySQL Server 5.5\bin" -PathType 'Machine' -``` - -Adds the target path to the system-wide PATH. - -## PARAMETERS - -### -IgnoredArguments -Allows splatting with arguments that do not apply. Do not use directly. - -```yaml -Type: Object[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Path -The full path to a location to add / ensure is in the PATH. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: PathToInstall - -Required: True -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -PathType -Which PATH to add it to. If specifying `Machine`, this requires admin privileges to run correctly. - -```yaml -Type: EnvironmentVariableTarget -Parameter Sets: (All) -Aliases: Scope, Type -Accepted values: Process, User, Machine - -Required: False -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -## NOTES - -This command will assert UAC/Admin privileges on the machine if -`-PathType 'Machine'`. - -This is used when the application/tool is not being linked by Chocolatey -(not in the lib folder). - -## RELATED LINKS - -[Uninstall-ChocolateyPath](xref:uninstall-chocolateypath) - -[Install-ChocolateyEnvironmentVariable](xref:install-chocolateyenvironmentvariable) - -[Get-EnvironmentVariable](xref:get-environmentvariable) - -[Set-EnvironmentVariable](xref:set-environmentvariable) - -[Get-ToolsLocation](xref:get-toolslocation) - -[Cmdlet Reference](xref:powershell-cmdlet-reference) - -[Function Reference](xref:powershell-reference) \ No newline at end of file diff --git a/input/en-us/create/cmdlets/Set-EnvironmentVariable.md b/input/en-us/create/cmdlets/Set-EnvironmentVariable.md deleted file mode 100644 index 54a73f777e..0000000000 --- a/input/en-us/create/cmdlets/Set-EnvironmentVariable.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -Description: Information on Set-EnvironmentVariable cmdlet -external help file: Chocolatey.PowerShell.dll-Help.xml -Module Name: Chocolatey.PowerShell -online version: https://docs.chocolatey.org/en-us/create/functions/set-environmentvariable -Order: 320 -RedirectFrom: - - docs/helpers-set-environment-variable - - docs/helperssetenvironmentvariable - - en-us/create/functions/set-environmentvariable -schema: 2.0.0 -Title: Set-EnvironmentVariable -xref: set-environmentvariable ---- - -# Set-EnvironmentVariable - -## SYNOPSIS -> :choco-info: **NOTE** -> -> Administrative Access Required when `-Scope 'Machine'.` - -DO NOT USE. Not part of the public API. Use `Install-ChocolateyEnvironmentVariable` instead. - -## SYNTAX - -``` -Set-EnvironmentVariable [-Name] <String> [[-Value] <String>] [[-Scope] <EnvironmentVariableTarget>] - [-IgnoredArguments <Object[]>] [<CommonParameters>] -``` - -## DESCRIPTION -Saves an environment variable. - -## EXAMPLES - -### Example 1 -```powershell -PS C:\> Set-EnvironmentVariable -Name MyApplicationPath -Value C:\test -Scope Machine -``` - -Sets the `MyApplicationPath` environment variable to `C:\test` at the system level. - -## PARAMETERS - -### -IgnoredArguments -Allows splatting with arguments that do not apply. Do not use directly. - -```yaml -Type: Object[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Name -The name of the environment variable to set. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Scope -The scope to set the environment variable at. - -```yaml -Type: EnvironmentVariableTarget -Parameter Sets: (All) -Aliases: -Accepted values: Process, User, Machine - -Required: False -Position: 2 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Value -The value to set the named environment variable to. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -## NOTES -This command will assert UAC/Admin privileges on the machine if -`-Scope 'Machine'`. - -## RELATED LINKS - -[Install-ChocolateyEnvironmentVariable](xref:install-chocolateyenvironmentvariable) - -[Uninstall-ChocolateyEnvironmentVariable](xref:uninstall-chocolateyenvironmentvariable) - -[Install-ChocolateyPath](xref:install-chocolateypath) - -[Get-EnvironmentVariable](xref:get-environmentvariable) - -[Cmdlet Reference](xref:powershell-cmdlet-reference) - -[Function Reference](xref:powershell-reference) \ No newline at end of file diff --git a/input/en-us/create/cmdlets/Test-ProcessAdminRights.md b/input/en-us/create/cmdlets/Test-ProcessAdminRights.md deleted file mode 100644 index 9365c9db2c..0000000000 --- a/input/en-us/create/cmdlets/Test-ProcessAdminRights.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -Description: Information on Test-ProcessAdminRights cmdlet -external help file: Chocolatey.PowerShell.dll-Help.xml -Module Name: Chocolatey.PowerShell -online version: https://docs.chocolatey.org/en-us/create/functions/test-processadminrights -Order: 350 -RedirectFrom: - - docs/helpers-test-process-admin-rights - - docs/helperstestprocessadminrights - - en-us/create/functions/test-processadminrights -schema: 2.0.0 -Title: Test-ProcessAdminRights -xref: test-processadminrights ---- - -# Test-ProcessAdminRights - -## SYNOPSIS -Tests whether the current process is running with administrative rights. - -## SYNTAX - -``` -Test-ProcessAdminRights [-IgnoredArguments <Object[]>] [<CommonParameters>] -``` - -## DESCRIPTION -This function checks whether the current process has administrative rights by checking if the current user identity is a member of the Administrators group. -It returns `$true` if the current process is running with administrative rights, `$false` otherwise. - -On Windows Vista and later, with UAC enabled, the returned value represents the actual rights available to the process, for example if it returns `$true`, the process is running elevated. - -## EXAMPLES - -### Example 1 -```powershell -PS C:\> Test-ProcessAdminRights -``` - -Outputs `$true` if the current process is elevated, otherwise `$false`. - -## PARAMETERS - -### -IgnoredArguments -Allows splatting with arguments that do not apply. Do not use directly. - -```yaml -Type: Object[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -### System.Boolean -Outputs `$true` if the current process has admin rights, otherwise `$false`. - -## NOTES - -## RELATED LINKS - -[Cmdlet Reference](xref:powershell-cmdlet-reference) - -[Function Reference](xref:powershell-reference) \ No newline at end of file diff --git a/input/en-us/create/cmdlets/Uninstall-ChocolateyPath.md b/input/en-us/create/cmdlets/Uninstall-ChocolateyPath.md deleted file mode 100644 index 7efb322ce7..0000000000 --- a/input/en-us/create/cmdlets/Uninstall-ChocolateyPath.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -Documentation: Information on Uninstall-ChocolateyPath cmdlet -external help file: Chocolatey.PowerShell.dll-Help.xml -Module Name: Chocolatey.PowerShell -online version: https://docs.chocolatey.org/en-us/create/functions/uninstall-chocolateypath -Order: 385 -schema: 2.0.0 -Title: Uninstall-ChocolateyPath -xref: uninstall-chocolateypath ---- - -# Uninstall-ChocolateyPath - -## SYNOPSIS -> :choco-info: **NOTE** -> -> Administrative Access Required when `-PathType 'Machine'.` - -This puts a directory to the PATH environment variable. - -## SYNTAX - -``` -Uninstall-ChocolateyPath [-Path] <String> [[-PathType] <EnvironmentVariableTarget>] - [-IgnoredArguments <Object[]>] [<CommonParameters>] -``` - -## DESCRIPTION -Ensures that the given path is not present in the given type of PATH environment variable as well as in the current session. - -## EXAMPLES - -### Example 1 -```powershell -PS C:\> Uninstall-ChocolateyPath -PathToUninstall "$($env:SystemDrive)\tools\gittfs" -``` - -Removes the target path from the current user's PATH environment variable. - -### Example 2 -```powershell -PS C:\> Uninstall-ChocolateyPath "$($env:SystemDrive)\Program Files\MySQL\MySQL Server 5.5\bin" -PathType 'Machine' -``` - -Removes the target path from the system-wide PATH environment variable. - -## PARAMETERS - -### -IgnoredArguments -Allows splatting with arguments that do not apply. Do not use directly. - -```yaml -Type: Object[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Path -The exact path to remove from the environment PATH. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: PathToUninstall - -Required: True -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -PathType -Which PATH to add it to. If specifying `Machine`, this requires admin privileges to run correctly. - -```yaml -Type: EnvironmentVariableTarget -Parameter Sets: (All) -Aliases: Scope, Type -Accepted values: Process, User, Machine - -Required: False -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -## NOTES -This command will assert UAC/Admin privileges on the machine if `-PathType 'Machine'`. -This is used when the application/tool is not being linked by Chocolatey (not in the lib folder). - -## RELATED LINKS - -[Install-ChocolateyPath](xref:install-chocolateypath) - -[Install-ChocolateyEnvironmentVariable](xref:install-chocolateyenvironmentvariable) - -[Get-EnvironmentVariable](xref:get-environmentvariable) - -[Set-EnvironmentVariable](xref:set-environmentvariable) - -[Get-ToolsLocation](xref:get-toolslocation) - -[Cmdlet Reference](xref:powershell-cmdlet-reference) - -[Function Reference](xref:powershell-reference) \ No newline at end of file diff --git a/input/en-us/create/cmdlets/Update-SessionEnvironment.md b/input/en-us/create/cmdlets/Update-SessionEnvironment.md deleted file mode 100644 index 5048f70aee..0000000000 --- a/input/en-us/create/cmdlets/Update-SessionEnvironment.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -Description: Information on Update-SessionEnvironment cmdlet -external help file: Chocolatey.PowerShell.dll-Help.xml -Module Name: Chocolatey.PowerShell -online version: https://docs.chocolatey.org/en-us/create/functions/update-sessionenvironment -Order: 400 -RedirectFrom: - - docs/helpers-update-session-environment - - docs/helpersupdatesessionenvironment - - en-us/create/functions/update-sessionenvironment -schema: 2.0.0 -Title: Update-SessionEnvironment -xref: update-sessionenvironment ---- - -# Update-SessionEnvironment - -## SYNOPSIS -Updates the environment variables of the current powershell session with any environment variable changes that may have occurred during a Chocolatey package install. - -## SYNTAX - -``` -Update-SessionEnvironment [-IgnoredArguments <Object[]>] [<CommonParameters>] -``` - -## DESCRIPTION -When Chocolatey installs a package, the package author may add or change certain environment variables that will affect how the application runs or how it is accessed. -Often, these changes are not visible to the current PowerShell session. -This means the user needs to open a new PowerShell session before these settings take effect which can render the installed application nonfunctional until that time. - -Use the Update-SessionEnvironment command to refresh the current PowerShell session with all environment settings possibly performed by Chocolatey package installs. - -## EXAMPLES - -### Example 1 -```powershell -PS C:\> Update-SessionEnvironment -``` - -Updates the current session environment variables. - -## PARAMETERS - -### -IgnoredArguments -Allows splatting with arguments that do not apply. Do not use directly. - -```yaml -Type: Object[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -## NOTES - -This method is also added to the user's PowerShell profile as `refreshenv`. When called as `refreshenv`, the method will provide additional output. - -Preserves `PSModulePath` as set by the process. - -## RELATED LINKS - -[Cmdlet Reference](xref:powershell-cmdlet-reference) - -[Function Reference](xref:powershell-reference) \ No newline at end of file diff --git a/input/en-us/create/cmdlets/index.md b/input/en-us/create/cmdlets/index.md deleted file mode 100644 index 6049c7aeb6..0000000000 --- a/input/en-us/create/cmdlets/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -Order: 35 -xref: powershell-cmdlet-reference -Title: PowerShell Cmdlet Reference -Description: PowerShell Cmdlet Helpers Reference ---- - -# PowerShell Cmdlet Helpers Reference - -See also: [PowerShell Functions Reference](xref:powershell-reference) - -## Summary - -In your Chocolatey packaging, you have the ability to use these commands (and others with Chocolatey's [PowerShell Extensions](xref:extensions)) to work with all aspects of software management. -Keep in mind Chocolatey's automation scripts are just PowerShell, so you can do anything you want. - -> :choco-info: **NOTE** -> -> These commands are for package scripts, not for use directly in PowerShell. This is in the create packages section, not the using Chocolatey section. - -## Complete List (alphabetical order) - - * [Get-EnvironmentVariable](xref:get-environmentvariable) - * [Get-EnvironmentVariableNames](xref:get-environmentvariablenames) - * [Install-ChocolateyPath](xref:install-chocolateypath) - * [Set-EnvironmentVariable](xref:set-environmentvariable) - * [Test-ProcessAdminRights](xref:test-processadminrights) - * [Uninstall-ChocolateyPath](xref:uninstall-chocolateypath) - * [Update-SessionEnvironment](xref:update-sessionenvironment) diff --git a/input/en-us/create/commands/api-key.md b/input/en-us/create/commands/api-key.md deleted file mode 100644 index 0843f45ac0..0000000000 --- a/input/en-us/create/commands/api-key.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -Order: 30 -xref: choco-command-apikey -Title: ApiKey -Description: ApiKey Command (choco apikey) -RedirectFrom: - - docs/commandsapikey - - docs/commands-apikey ---- - -<!-- This file is automatically generated based on output from https://github.com/chocolatey/choco/blob/master/src/chocolatey/infrastructure.app/commands/ChocolateyApiKeyCommand.cs using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). If the file is not found, it is not part of the open source edition of Chocolatey or the name of the file is different. --> - -# ApiKey Command (choco apikey) - -This lists API keys that are set or sets an api key for a particular - source so it doesn't need to be specified every time. - -Anything that doesn't contain source and key will list API keys. - -## Usage - - choco apikey [<options/switches>] - choco setapikey [<options/switches>] - -## Examples - - choco apikey - choco apikey -s https://somewhere/out/there - choco apikey list - choco apikey list -s https://somewhere/out/there - choco apikey add -s="https://somewhere/out/there/" -k="value" - choco apikey add -s "https://push.chocolatey.org/" -k="123-123123-123" - choco apikey add -s "http://internal_nexus" -k="user:password" - choco apikey remove -s https://somewhere/out/there - -For source location, this can be a folder/file share or an -http location. When it comes to urls, they can be different from the packages -url (where packages are searched and installed from). As an example, for -Chocolatey's community package package repository, the package url is -https://community.chocolatey.org/api/v2/, but the push url is https://push.chocolatey.org -(and the deprecated https://chocolatey.org/ as a push url). Check the -documentation for your choice of repository to learn what the push url is. - -For the key, this can be an apikey that is provided by your source repository. -With some sources, like Nexus, this can be a NuGet API key or it could be a -user name and password specified as 'user:password' for the API key. Please see -your repository's documentation (for Nexus, please see -https://ch0.co/nexus2apikey). - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Connecting to Chocolatey.org (Community Package Repository) - -In order to save your API key for https://push.chocolatey.org/, - log in (or register, confirm and then log in) to - https://push.chocolatey.org/, go to https://push.chocolatey.org/account, - copy the API Key, and then use it in the following command: - - choco apikey add -k <your key here> -s https://push.chocolatey.org/ - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - - 2: nothing to do, apikey already set (enhanced) - -> :choco-info: **NOTE** -> -> Starting in v2.3.0, if you have the feature 'useEnhancedExitCodes' - turned on, then choco will provide enhanced exit codes that allow - better integration and scripting. - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -s, --source=VALUE - Source [REQUIRED] - The source location for the key - - -k, --key, --apikey, --api-key=VALUE - ApiKey - The API key for the source. This is the authentication that - identifies you and allows you to push to a source. With some sources - this is either a key or it could be a user name and password specified - as 'user:password'. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco apikey -h`. - diff --git a/input/en-us/create/commands/convert.md b/input/en-us/create/commands/convert.md deleted file mode 100644 index a1a1b7a245..0000000000 --- a/input/en-us/create/commands/convert.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -Order: 60 -xref: choco-command-convert -Title: Convert -Description: Convert Command (choco convert) -RedirectFrom: - - docs/commandsconvert - - docs/commands-convert ---- - -<!-- This file is automatically generated based on output from https://github.com/chocolatey/choco/blob/master/src/chocolatey/infrastructure.app/commands/ChocolateyConvertCommand.cs using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). If the file is not found, it is not part of the open source edition of Chocolatey or the name of the file is different. --> - -# Convert Command (choco convert) - -### Package Converter - -Converts a NuGet Package into an `intunewin` file to use with Microsoft Endpoint Manager. - - -## Usage - - choco convert <pkg> [<options/switches>] - -## Examples - - choco convert sysinternals.nupkg --to-format=intune - - choco convert notepadplusplus.nupkg --to-format=intune - -## See It In Action - -Coming soon - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - --to, --to-format=VALUE - To Format - Format that we're converting packages to. Must be specified - for convert to work. - - --include-all, --includeall - Include all nupkg files in the working directory - - -i, --ignoredependencies, --ignore-dependencies - IgnoreDependencies - Ignore dependencies when installing package(s). - Defaults to false. - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco convert -h`. - diff --git a/input/en-us/create/commands/index.md b/input/en-us/create/commands/index.md deleted file mode 100644 index 8df0c8aa31..0000000000 --- a/input/en-us/create/commands/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 30 -xref: choco-create-commands -Title: Commands -Description: These are the Chocolatey commands that are typically used when creating a Chocolatey package ---- \ No newline at end of file diff --git a/input/en-us/create/commands/new.md b/input/en-us/create/commands/new.md deleted file mode 100644 index aff483bb8d..0000000000 --- a/input/en-us/create/commands/new.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -Order: 10 -xref: choco-command-new -Title: New -Description: New Command (choco new) -RedirectFrom: - - docs/commandsnew - - docs/commands-new ---- - -<!-- This file is automatically generated based on output from https://github.com/chocolatey/choco/blob/master/src/chocolatey/infrastructure.app/commands/ChocolateyNewCommand.cs using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). If the file is not found, it is not part of the open source edition of Chocolatey or the name of the file is different. --> - -# Package Builder Command (choco new) - -Chocolatey [Licensed editions](https://chocolatey.org/compare) include some level of Package Builder. - - - Professional can take advantage of Package Builder UI minus the auto-detection - - Business can use `--file` or Package Builder UI to generate a fully ready to go - unattended software deployment in seconds. Right-click, 'Create Package...' - - Business can use `--from-programs-and-features` to generate packages directly - from Programs and Features! - -See more information about [Package Builder features](xref:package-builder) - - -# New Command (choco new) - -Chocolatey will generate package specification files for a new package. - -## Usage - - choco new <name> [<options/switches>] [<property=value> <propertyN=valueN>] - -Possible properties to pass: - packageversion - maintainername - maintainerrepo - installertype - url - url64 - silentargs - -> :choco-info: **NOTE** -> -> You can pass arbitrary property value pairs - through to templates. This really unlocks your ability to create - packages automatically! - -> :choco-info: **NOTE** -> -> [Chocolatey for Business](https://chocolatey.org/compare) can create complete packages by just - pointing the new command to native installers! - -> :choco-info: **NOTE** -> -> [Chocolatey for Business](https://chocolatey.org/compare) can also download and internalize remote - resources from existing packages so that existing packages can be used - without being tied to the internet. - This is called automatic recompile. - -## Examples - - choco new bob - choco new bob -a --version 1.2.0 maintainername="'This guy'" - choco new bob silentargs="'/S'" url="'https://somewhere/out/there.msi'" - choco new bob --outputdirectory Packages - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -a, --auto, --automaticpackage - AutomaticPackage - Generate automatic package instead of normal. - Defaults to false - - -t, --template, --template-name=VALUE - TemplateName - Use a named template in - C:\ProgramData\chocolatey\templates\templatename instead of built-in - template. - - --name=VALUE - Name [Required]- the name of the package. Can be passed as first - parameter without "--name=". - - --version=VALUE - Version - the version of the package. Can also be passed as the property - PackageVersion=somevalue - - --maintainer=VALUE - Maintainer - the name of the maintainer. Can also be passed as the - property MaintainerName=somevalue - - --out, --outdir, --outputdirectory, --output-directory=VALUE - OutputDirectory - Specifies the directory for the created Chocolatey - package file. If not specified, uses the current directory. - - --built-in, --built-in-template, --originaltemplate, --original-template, --use-original-template, --use-built-in-template - BuiltInTemplate - Use the original built-in template instead of any - override. - - --file, --url=VALUE - Location of binary. In [Chocolatey for Business](https://chocolatey.org/compare), file is used for auto- - detection (native installer, zip, patch/upgrade file, or remote url to - download first) to completely create a package with proper silent - arguments! Can be 32-bit or 64-bit architecture. Available in licensed - editions only. - See https://docs.chocolatey.org/en-us/features/package-builder - - --file64, --url64=VALUE - Optional - used when specifying both a 32-bit and a 64-bit file. Can be - an installer or a zip, or remote url to download. Available in licensed - editions only. - - --keepremote, --keep-remote, --originallocation, --original-location, --useoriginallocation, --use-original-location, --useoriginalfileslocation, --use-original-files-location - Use Original Files Location - when using file or url, use the original - location in packaging. Available in licensed editions only. - - --checksum, --downloadchecksum, --download-checksum=VALUE - Download Checksum - checksum to verify File/Url with. Defaults to empty. - Available in licensed editions only. - - --checksum64, --checksumx64, --downloadchecksumx64, --download-checksum-x64=VALUE - Download Checksum 64-bit - checksum to verify File64/Url64 with. - Defaults to empty. Available in licensed editions only. - - --checksumtype, --checksum-type, --downloadchecksumtype, --download-checksum-type=VALUE - Download Checksum Type - checksum type for File/Url (and optional - separate 64-bit files when specifying both). Used in conjunction with - Download Checksum and Download Checksum 64-bit. Available values are - 'md5', 'sha1', 'sha256' or 'sha512'. Defaults to 'sha256'. Available in - Business editions only. - - --pauseonerror, --pause-on-error - Pause on Error - Pause when there is an error with creating the package. - Available in licensed editions only. - - --buildpackage, --build-package, --build-packages - Build Package - Attempt to compile the package after creating it. - Available in licensed editions only. - - --fromprograms, --from-programs, --fromprogramsandfeatures, --from-programs-and-features - Generate Packages From Installed Software - Generate packages from the - installed software on a system (does not handle dependencies). Available - in Business editions only. - - --removearchitecture, --removearchitecturefromname, --remove-architecture, --remove-architecture-from-name - Remove Architecture From Name - Remove x86, x64, 64-bit, etc from the - package id. Default setting is to remove architecture. Available in - Business editions only. - - --includearchitecture, --includearchitectureinname, --include-architecture, --include-architecture-in-name - Include Architecture in Package Name - Leave x86, x64, 64-bit, etc as - part of the package id. Default setting is to remove architecture. - Available in Business editions only. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco new -h`. - diff --git a/input/en-us/create/commands/pack.md b/input/en-us/create/commands/pack.md deleted file mode 100644 index 31315e0bff..0000000000 --- a/input/en-us/create/commands/pack.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -Order: 20 -xref: choco-command-pack -Title: Pack -Description: Pack Command (choco pack) -RedirectFrom: - - docs/commandspack - - docs/commands-pack ---- - -<!-- This file is automatically generated based on output from https://github.com/chocolatey/choco/blob/master/src/chocolatey/infrastructure.app/commands/ChocolateyPackCommand.cs using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). If the file is not found, it is not part of the open source edition of Chocolatey or the name of the file is different. --> - -# Pack Command (choco pack) - -Chocolatey will attempt to package a nuspec into a compiled nupkg. - -> :choco-info: **NOTE** -> -> You can pass arbitrary property value pairs through to nuspecs. - These will replace variables formatted as `$property$` with the value passed. - -## Usage - - choco pack [<path to nuspec>] [<options/switches>] [<property=value>] - -## Examples - - choco pack - choco pack --version 1.2.3 configuration=release - choco pack path/to/nuspec - choco pack --outputdirectory build - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - --version=VALUE - Version - The version you would like to insert into the package. - - --out, --outdir, --outputdirectory, --output-directory=VALUE - OutputDirectory - Specifies the directory for the created Chocolatey - package file. If not specified, uses the current directory. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco pack -h`. - diff --git a/input/en-us/create/commands/push.md b/input/en-us/create/commands/push.md deleted file mode 100644 index e576d04a08..0000000000 --- a/input/en-us/create/commands/push.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -Order: 40 -xref: choco-command-push -Title: Push -Description: Push Command (choco push) -RedirectFrom: - - docs/commandspush - - docs/commands-push ---- - -<!-- This file is automatically generated based on output from https://github.com/chocolatey/choco/blob/master/src/chocolatey/infrastructure.app/commands/ChocolateyPushCommand.cs using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). If the file is not found, it is not part of the open source edition of Chocolatey or the name of the file is different. --> - -# Push Intune Packages Command (choco push) - -[Chocolatey for Business](https://chocolatey.org/compare) starting in version 3.0.0 include the ability to push `intunewin` packages to Microsoft Endpoint Manager Intune. - -## Usage - - choco push <pkg> [<options/switches>] - -## Examples - - choco push 1password.intunewin --source=$TenantID --key=$ClientId:=$ClientSecret - - choco push notepadplusplus.intunewin --source=$TenantID --key=$ClientId: --client-code=$ClientCode --redirect-uri=$RedirectUri - -## See It In Action - -Coming soon - -# Push Command (choco push) - -Chocolatey will attempt to push a compiled nupkg to a package feed. - -A feed can be a local folder, a file share, the [community feed](https://community.chocolatey.org/packages) - (https://push.chocolatey.org/), or a custom/private feed. For web - feeds, it has a requirement that it implements the proper OData - endpoints required for NuGet packages. - -## Usage - - choco push [<path to nupkg>] [<options/switches>] - -> :choco-info: **NOTE** -> -> If there is more than one nupkg file in the folder, the command - will require specifying the path to the file. - -## Examples - - choco push --source https://push.chocolatey.org/ - choco push --source "'https://push.chocolatey.org/'" --execution-timeout 500 - choco push --source "'https://push.chocolatey.org/'" -k="'123-123123-123'" - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Troubleshooting - -To use this command, you must have your API key saved for the community - feed (chocolatey.org) or the source you want to push to. Or you can - explicitly pass the apikey to the command. See [`apikey`](xref:choco-command-apikey) command help - for instructions on saving your key: - - choco apikey -? - -A common error is `Failed to process request. 'The specified API key - does not provide the authority to push packages.' The remote server - returned an error: (403) Forbidden..` This means the package already - exists with a different user (API key). The package could be unlisted. - You can verify by going to https://community.chocolatey.org/packages/packageName. - Please contact the administrators of https://community.chocolatey.org/ if you see this - and you don't see a good reason for it. - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -s, --source=VALUE - Source - The source we are pushing the package to. Use https://pus- - h.chocolatey.org/ to push to [community feed](https://community.chocolatey.org/packages). - - -k, --key, --apikey, --api-key=VALUE - ApiKey - The API key for the source. If not specified (and not local - file source), does a lookup. If not specified and one is not found for - an https source, push will fail. - - --client-code, --clientcode, --code=VALUE - Client Code - (delegate permissions) the client code generated for - delegating access by a user to the Intune endpoints. - - --redirect-url, --redirect, --redirecturl=VALUE - Redirect URL - (delegate permissions) the URL used when requesting the - client code. - - --endpoint=VALUE - Endpoint - The Intune API endpoint to use. Defaults to beta endpoint, - can fallback to `v1.0` should the beta change and cause issues. - - --skip-cleanup - Skip Cleanup - Don't cleanup local files when pushing to Intune. On a - failed push to Intune, don't attempt to cleanup the Intune packages. - - --use-self-service, --force-self-service - Force the command to be handled through the self-service when not - configured to allow this command. This option requires the features for - self-service and self-service command override to be enabled. Business - editions only (licensed version 5.0.0+). - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco push -h`. - diff --git a/input/en-us/create/commands/template.md b/input/en-us/create/commands/template.md deleted file mode 100644 index 4852082426..0000000000 --- a/input/en-us/create/commands/template.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -Order: 50 -xref: choco-command-template -Title: Template -Description: Template Command (choco template) -RedirectFrom: - - docs/commandstemplate - - docs/commands-template ---- - -<!-- This file is automatically generated based on output from https://github.com/chocolatey/choco/blob/master/src/chocolatey/infrastructure.app/commands/ChocolateyTemplateCommand.cs using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). If the file is not found, it is not part of the open source edition of Chocolatey or the name of the file is different. --> - -# Template Command (choco template) - -List information installed templates. - -Both manually installed templates and templates installed via - .template packages are displayed. -## Usage - - choco template [list]|info [<options/switches>] -## Examples - - choco template - choco templates - choco template list - choco template info --name msi - choco template list --reduce-output - choco template list --verbose - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -n, --name=VALUE - The name of the template to get information about. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco template -h`. - diff --git a/input/en-us/create/commands/templates.md b/input/en-us/create/commands/templates.md deleted file mode 100644 index b3d5f5806d..0000000000 --- a/input/en-us/create/commands/templates.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -Order: 55 -xref: choco-command-templates -Title: Templates -Description: Templates Command (choco templates) -RedirectFrom: - - docs/commandstemplates - - docs/commands-templates -ShowInNavbar: false -ShowInSidebar: false ---- - -<!-- This file is automatically generated based on output from https://github.com/chocolatey/choco/blob/master/src/chocolatey/infrastructure.app/commands/ChocolateyTemplatesCommand.cs using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). If the file is not found, it is not part of the open source edition of Chocolatey or the name of the file is different. --> - -# Template Command (choco templates) - -List information installed templates. - -Both manually installed templates and templates installed via - .template packages are displayed. -## Usage - - choco template [list]|info [<options/switches>] -## Examples - - choco template - choco templates - choco template list - choco template info --name msi - choco template list --reduce-output - choco template list --verbose - -> :choco-info: **NOTE** -> -> See scripting in [how to pass arguments](xref:choco-commands#how-to-pass-options-switches) (`choco -?`) for how to - write proper scripts and integrations. - - -## Exit Codes - -Exit codes that normally result from running this command. - -Normal: - - 0: operation was successful, no issues detected - - -1 or 1: an error has occurred - -If you find other exit codes that we have not yet documented, please - file a ticket so we can document it at - https://github.com/chocolatey/choco/issues/new/choose. - - -## Options and Switches - -> :choco-info: **NOTE** -> -> Options and switches apply to all items passed, so if you are - running a command like install that allows installing multiple - packages, and you use `--version=1.0.0`, it is going to look for and - try to install version 1.0.0 of every package passed. So please split - out multiple package calls when wanting to pass specific options. - -Includes [default options/switches](xref:choco-commands#default-options-and-switches) (included below for completeness). - -~~~ - - -?, --help, -h - Prints out the help menu. - - --online - Online - Open help for specified command in default browser application. - This option only works when used in combintation with the -?/--help/-h - option. Available in 2.0.0+ - - -d, --debug - Debug - Show debug messaging. - - -v, --verbose - Verbose - Show verbose messaging. Very verbose messaging, avoid using - under normal circumstances. - - --trace - Trace - Show trace messaging. Very, very verbose trace messaging. Avoid - except when needing super low-level .NET Framework debugging. - - --nocolor, --no-color - No Color - Do not show colorization in logging output. This overrides - the feature 'logWithoutColor', set to 'False'. - - --acceptlicense, --accept-license - AcceptLicense - Accept license dialogs automatically. Reserved for - future use. - - -y, --yes, --confirm - Confirm all prompts - Chooses affirmative answer instead of prompting. - Implies --accept-license - - -f, --force - Force - force the behavior. Do not use force during normal operation - - it subverts some of the smart behavior for commands. - - --noop, --whatif, --what-if - NoOp / WhatIf - Don't actually do anything. - - -r, --limitoutput, --limit-output - LimitOutput - Limit the output to essential information - - --timeout, --execution-timeout=VALUE - CommandExecutionTimeout (in seconds) - The time to allow a command to - finish before timing out. Overrides the default execution timeout in the - configuration of 2700 seconds. Supply '0' to disable the timeout. - - -c, --cache, --cachelocation, --cache-location=VALUE - CacheLocation - Location for download cache, defaults to %TEMP% or value - in chocolatey.config file. - - --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build - AllowUnofficialBuild - When not using the official build you must set - this flag for choco to continue. - - --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output - FailOnStandardError - Fail on standard error output (stderr), typically - received when running external commands during install providers. This - overrides the feature failOnStandardError. - - --use-system-powershell - UseSystemPowerShell - Execute PowerShell using an external process - instead of the built-in PowerShell host. Should only be used when - internal host is failing. - - --no-progress - Do Not Show Progress - Do not show download progress percentages. - - --proxy=VALUE - Proxy Location - Explicit proxy location. Overrides the default proxy - location of ''. - - --proxy-user=VALUE - Proxy User Name - Explicit proxy user (optional). Requires explicit - proxy (`--proxy` or config setting). Overrides the default proxy user of - ''. - - --proxy-password=VALUE - Proxy Password - Explicit proxy password (optional) to be used with user - name. Encrypted. Requires explicit proxy (`--proxy` or config setting) - and user name (`--proxy-user` or config setting). Overrides the default - proxy password. - - --proxy-bypass-list=VALUE - ProxyBypassList - Comma separated list of regex locations to bypass on - proxy. Requires explicit proxy (`--proxy` or config setting). Overrides - the default proxy bypass list of ''. - - --proxy-bypass-on-local - Proxy Bypass On Local - Bypass proxy for local connections. Requires - explicit proxy (`--proxy` or config setting). Overrides the default - proxy bypass on local setting of 'True'. - - --log-file=VALUE - Log File to output to in addition to regular loggers. - - --skipcompatibilitychecks, --skip-compatibility-checks - SkipCompatibilityChecks - Prevent warnings being shown before and after - command execution when a runtime compatibility problem is found between - the version of Chocolatey and the Chocolatey Licensed Extension. - Available in 1.1.0+ - - --ignore-http-cache - IgnoreHttpCache - Ignore any HTTP caches that have previously been - created when querying sources, and create new caches. Available in 2.1.0+ - - -n, --name=VALUE - The name of the template to get information about. - -~~~ - -[Command Reference](xref:choco-commands) - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `choco templates -h`. - diff --git a/input/en-us/create/create-packages-quick-start.md b/input/en-us/create/create-packages-quick-start.md deleted file mode 100644 index e1b627b4ed..0000000000 --- a/input/en-us/create/create-packages-quick-start.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -Order: 20 -xref: create-packages-quick-start -Title: Quick Start -Description: The quick start guide on creating Chocolatey packages -RedirectFrom: - - docs/createpackagesquickstart - - docs/create-packages-quick-start ---- - -## Creating Chocolatey Packages - TL;DR version - -Here's a TL;DR quick start version of the package creating tutorial. Follow these steps to create a simple package. - -**Problem?** Read the detailed version: [Creating Chocolatey Packages](xref:create-packages) - -## Prerequisites - -* You have Chocolatey installed. -* You've read [What are Chocolatey Packages?](xref:getting-started#what-are-chocolatey-packages) first. -* You know how a package works - * A package contains a `nuspec` file. This defines the package. ([Docs](xref:create-packages#nuspec)) - * A package may contain embedded software. - * A package may contain an installation script. This can be [very simple](#examples). - -## Quick start guide - -* **Generate new package**: - * `choco new -h` will get you started seeing options available to you. - * Once you figured out all of your options, you should move forward with generating your template. -* **Edit template** using common sense - * `cd package-name` - * Edit the `package-name.nuspec` configuration file. - * Edit the `./tools/chocolateyInstall.ps1` install script. - * Make sure you figure out the installer's silent mode. Use [Universal Silent Switch Finder](http://unattended.sourceforge.net/installers.php), which is available as a Choco package: `choco install ussf` - * You __must__ save your files with _UTF-8_ character encoding without BOM. ([Details](xref:create-packages#character-encoding)) -* **Build the package** - * Still in package directory - * `choco pack` - * "Successfully created package-name.1.1.0.nupkg" -* **Test the package** - * **Testing should probably be done on a Virtual Machine** - * In your package directory, use: - * `choco install package-name --source .` (package-name is the id element in the nuspec) -* **Push the package** to the Chocolatey community package repository: - * Get a Chocolatey account: - * [Register](https://chocolatey.org/account/register) - * Copy the API key from [your Chocolatey account](https://chocolatey.org/account). - * `choco apikey --api-key [API_KEY_HERE] -source https://push.chocolatey.org/` - * `choco push package-name.1.1.0.nupkg --source https://push.chocolatey.org/` - nupkg file can be omitted if it is the only one in the directory. - -## Common Mistakes - -* **NuSpec** - * **id** is the package name and should meet the following criteria: - * should contain no spaces and weird characters. - * should be lowercase. - * should separate spaces in the software name with `-` e.g. `classic-shell`. Yes, we realize there are a lot of older packages not following this convention. - * **version** is a dot-separated identifier containing a maximum of 4 numbers. e.g. _1.0_ or _2.4.0.16_ - except for prerelease packages - -## Environmental Variables - -* `%ChocolateyInstall%` - Chocolatey installation directory -* `%ChocolateyInstall%\lib\package-name` - Package directory -* `%cd%` or `$pwd` - current directory -* Environment variable reference available in the README when using `choco new` or [online](xref:powershell-reference#variables). - -## Examples - -Here are some simple examples. - -> :choco-info: **NOTE** -> -> This needs updated with checksums and newer package concepts. Please run `choco new` when creating packages as it contains all of the most up to date notes. - -### chocolateyInstall.ps1 for .exe installer - -```powershell -$name = 'Package Name' -$installerType = 'exe' -$url = 'http://path/to/download/installer.exe' -$silentArgs = '/VERYSILENT' - -Install-ChocolateyPackage $name $installerType $silentArgs $url -``` - -> :choco-info: **NOTE** -> -> You have to figure out the command line switch to make the installer silent, e.g. **/VERYSILENT**. This changes from installer to installer. - -### chocolateyInstall.ps1 for .msi installer - -> :choco-info: **NOTE** -> -> Please maintain compatibility with Posh v2. Not every OS we support is on Posh v2 (nor comes OOB with Posh v3+). It's best to work with the widest compatibility of systems out there. - -```powershell -$packageName = 'Package Name' -$installerType = 'msi' -$url = 'http://path/to/download/installer_x86.msi' -$url64 = 'http://path/to/download/installer_x64.msi' -$silentArgs = '/quiet' -$validExitCodes = @(0,3010) - -Install-ChocolateyPackage $packageName $installerType $silentArgs $url $url64 -validExitCodes $validExitCodes -``` - -### Parsing Package Parameters - -For a complete example of how you can use the PackageParameters argument of the ```choco install``` command, see this [How-To](xref:parse-package-parameters). - -## Tips - -* If you cannot find the installer silent mode, you can try an old tool called [Universal Silent Switch Finder 1.5.0.0](http://www.softpedia.com/progDownload/Universal-Silent-Switch-Finder-Download-180984.html) - `choco install ussf`. diff --git a/input/en-us/create/create-packages.md b/input/en-us/create/create-packages.md deleted file mode 100644 index b3865eb91c..0000000000 --- a/input/en-us/create/create-packages.md +++ /dev/null @@ -1,517 +0,0 @@ ---- -Order: 10 -xref: create-packages -Title: Create Packages -Description: How to start creating your own Chocolatey packages -RedirectFrom: - - docs/create-packages - - docs/CreatePackages ---- - -# Creating Chocolatey Packages - -## Summary - -See [What are Chocolatey Packages?](xref:getting-started#what-are-chocolatey-packages) first. - -> :choco-info: **NOTE** -> -> When you host internal packages, those packages can embed software and/or point to internal shares. You are not subject to software distribution rights like the packages on the community feed, so you can create packages that are more reliable and secure. - -First you should determine if you are making a self-contained package or (also) using automation scripts. You should also consider creating [automatic packages](xref:automatic-packaging) for the best maintainability over time. - -1. Run `choco new -h` to get a feel for what you can pass e.g `choco new bob` (to create a package named `bob`) -1. Note all the rules below. This will help you, especially in publishing to the community feed (https://chocolatey.org) - -### Self-Contained? - -If you have a self-contained package, you can remove the automation scripts -entirely and just include the runtime executables, they will automatically get shimmed, -which puts them on the path. Ensure you have the [legal right to distribute](xref:legal) -the application though. You should read up on the Shim Generation section -below though to familiarize yourself on what to do with GUI applications -and/or ignoring shims (also known as batch redirects). - -### Including the Software Installer in the Package - -Sometimes called embedding the binaries, there are functions in the automation scripts you can call that will use the installers directly from the package instead of downloading first. This makes for the most reliable and deterministic packages, but ensure you have the [legal right to distribute](xref:legal) the software first if publishing to a public location (like the community package repository). - -### Automation Scripts - -You have a powerful use of Chocolatey, as you are using PowerShell. So you can do just about anything you need. Choco has some very handy [built-in functions](xref:powershell-reference) that you can use, these are sometimes called -[helpers](xref:powershell-reference). - -## Table of Contents - -1. [Rules](#rules-to-be-observed-before-publishing-packages) -1. [Encoding](#character-encoding) -1. Learning about NuGet (and Chocolatey) Packages in general - [Information](#okay-how-do-i-create-packages) and [Nuspec](#nuspec) -1. [Description/Release Notes Recommendations](#package-description-and-release-notes) -1. [Limit Windows Versions](#install-only-on-some-versions-of-windows) -1. [Install paths](#installation-paths) -1. [Upgrading](#upgrading) and [Uninstalling](#uninstalling) -1. [Naming your package](#naming-your-package) -1. [Versioning](#versioning-recommendations) (and [package fix version notation](#package-fix-version-notation)) -1. [Icons](#package-icon-guidelines) -1. [Exclude executables from shims](#how-do-i-exclude-executables-from-getting-batch-redirects) -1. [Make shim for GUI application](#how-do-i-set-up-batch-redirects-for-applications-that-have-a-gui) -1. [Localization](#internationalization-and-localization-of-packages) -1. [Building](#build-your-package) / [Testing](#testing-your-package) / [Pushing](#push-your-package) -1. [Maintainer magic - automatically updating packaging](xref:automatic-packaging) -1. [Taking over existing package](xref:package-maintainer-handover) - -## Quick Start Guide - -If you think you got what it takes and just want to know the basic steps to get a package out, there is a special [Quick Start Guide](xref:create-packages-quick-start) for you. - -> :choco-info: **NOTE** -> -> This doesn't exempt you from observing the rules, requirements and guidelines (noted below). - -## Rules to be Observed Before Publishing Packages - -There are a few rules that you have to follow before pushing packages to chocolatey.org: - -1. **Don't package illegal software.** Packages of software that is illegal in most countries in the world are prohibited to publish on Chocolatey.org. This applies in particular to software that violates the copyright, pirated software and activation cracks. Remember that this also affects software that is especially designed to accomplish software piracy. -1. **Do not include software in a package that you don't have the right to distribute.** Please see [Distribution Rights](xref:legal#distributions) for more information. Any package found not in compliance with this will be removed immediately. Instead you can download binaries from official distribution locations at runtime. -1. **Packaging commercial or trial software?** Clearly state this in the package description. Does it require an activation key? Is there a trial period if you don't have a key? How long is this trial period? -1. **Only post publicly relevant packages.** You should consider whether this package is useful for others. If that is not the case, it shouldn't be published on Chocolatey.org. Reasons for that can be if the package would require a very customized configuration. You can host your personal packages on [MyGet](https://www.myget.org/) and still be able to install them with Chocolatey using the `-source` parameter. -1. **Do not publish junk or malware** packages. -1. **Don't package software _containing_ malware.** Packages of software that comes with bundled adware, spyware or other unrelated software that installs even in silent mode, are not allowed. But if you can figure out how to install the desired software without this unrelated software, it is allowed to publish the package. That can be accomplished for example with additional command line switches or by adding specific values to the registry. Examples of packages which make use of this are [PDFCreator](https://github.com/stack72/MyChocolateyPackages/tree/master/PDFCreator) and [CCleaner](https://github.com/tonigellida/chocolateyautomaticpackages/tree/master/ccleaner). -1. **Don't package software that is already packaged**. Use the search function in the [Chocolatey Community Repository](https://community.chocolatey.org/packages) and look if there is already a package for the desired software. If you would like to improve the already existing package or if you have suggestions, just contact the package maintainer or open a pull request at the maintainer’s package repository. -1. **Don't include other required software if there's a package of it.** If a package requires other software of which there is already a package, the already existing package should be used as [dependency](http://docs.nuget.org/create/nuspec-reference#specifying-dependencies) instead. -1. **Split dependencies into multiple packages.** Try to split up packages as much as possible. If for example a program comes with additional modules/installers that are optional, make different packages for them instead of including all the things into one package. This idea is already widely applied for Linux packages, because it leads to a more lightweight system and reduces potential issues and conflicts. -1. **Use a simple intuitive lowercase name for the package**. See the [package naming guidelines](#naming-your-package) for details. (If you are a reviewer/moderator, this is considered a guideline). - -Is your package unqualified for the Chocolatey feed, but you like to be able to install it through Chocolatey? One alternative would be to host your package on MyGet. See [Hosting Chocolatey Packages on MyGet](xref:hosting-chocolatey-packages-on-myget). - -## Character Encoding - -- **Use the UTF-8 character encoding** for the `*.nuspec` and `*.ps1` files. If you don’t respect this rule, some characters are not displayed correctly in the [Chocolatey Community Repository](http://community.chocolatey.org/packages), because if defaults to `UTF-8`. -- **Byte Order Mark (BOM) is optional for `*.nuspec`.**. A `BOM` is not required but it won't hurt anything if it is found. -- **PowerShell scripts need to be saved in UTF-8 with `BOM`**. PowerShell is ignoring the standards and needs a `BOM` in order to recognize scripts as `UTF-8`. Otherwise it processes non `ASCII` characters incorrectly. -- Don’t use the default Windows Editor. While newer versions of Notepad have improved its ability to handle line endings and UTF-8 w/out BOM, it is still behind in capabilities as compared to other editors. Alternatives: - - [Visual Studio Code](https://community.chocolatey.org/packages/vscode) - - [Notepad++](http://community.chocolatey.org/packages/notepadplusplus) - - [Geany](http://community.chocolatey.org/packages/geany) -- Use this **XML declaration**: `<?xml version="1.0" encoding="utf-8"?>`. - -> :choco-info: **NOTE** -> -> There is a lot of confusion in the world of character encodings: For example, `ANSI` is an incorrect term for the internal Windows character encodings, e. g. `Windows-1252`. But you should not use this encoding family anyway. - -## What Version of the Software Should I Package? - -The main release of a product versions are usually sufficient. If there are also beta versions available and you would rather have that, then please create both the official release and the beta (and set the beta as a prerelease when pushing the item to community.chocolatey.org). Regular users of packages may want to use official releases only and not betas. - -> :choco-info: **NOTE** -> -> Both of these have the SAME package id, just different versions. - -## How do I Create Packages? - -There are three main elements to a Chocolatey package. Only the nuspec is required (#1 below). - -1. [Nuspec](xref:create-packages#nuspec) -1. [chocolateyInstall.ps1](xref:chocolatey-install-ps1) - check out the [helper reference](xref:powershell-reference) -1. any application files to include (it is highly suggested that you are the author in this case or you have the right to [distribute files](xref:legal)). EXE files in the package/downloaded to package folder from chocolateyInstall.ps1 will get a link to the command line. -1. chocolateyUninstall.ps1, for uninstalling your package. See [helper reference](xref:powershell-reference) for functions available in your script. - -> :choco-info: **NOTE** -> -> Please maintain compatibility with Posh v2. Not every OS we support is on Posh v2 (nor comes OOB with Posh v3+). It's best to work with the widest compatibility of systems out there. - -There is a video showing the creation of a package: [http://www.youtube.com/watch?v=Wt_unjS_SUo](http://www.youtube.com/watch?v=Wt_unjS_SUo) -The video is a bit outdated in showing the contents of the chocolateyInstall.ps1. Have a look at what the [chocolateyInstall.ps1](https://github.com/ferventcoder/chocolatey-packages/blob/master/manual/windirstat/tools/chocolateyInstall.ps1) looks like now: - -```powershell -$packageName = 'windirstat' -$fileType = 'exe' -$url = 'http://prdownloads.sourceforge.net/windirstat/windirstat1_1_2_setup.exe' -$silentArgs = '/S' - -Install-ChocolateyPackage $packageName $fileType $silentArgs $url -``` - -## When Will my Custom Scripts be Run? - -The table below shows which scripts are available, and which command(s) will cause them to be run. - -Script Name | Install | Upgrade | Uninstall ------------------------------------------------|---------|---------|---------- -chocolateyBeforeModify.ps1 | | Yes | Yes -chocolateyInstall.ps1 | Yes | Yes | -chocolateyUninstall.ps1 | | | Yes - -> :choco-info: **NOTE** -> -> In the upgrade scenario, the chocolateyInstall.ps1 script will be the one included in the new package. The chocolateyBeforeModify.ps1 script will be the one from the previously installed package. - -## Nuspec - -The `Chocolatey` Windows package manager uses the same infrastructure as [NuGet](http://nuget.org/), the Visual Studio package manager by Outercurve Foundation (sponsored by Microsoft). Therefore packages are based on the same principles. One of those is a package description (specification) in `xml` format, known as the `Nuspec`. - -The `Nuspec` contains basic information such as the version, license, maintainer, and package dependencies. `Chocolatey` includes additional optional functionality on top of [NuGet's Nuspec format](http://docs.nuget.org/docs/reference/nuspec-reference) - the best way to determine currently supported features is to create a test package, and look at the generated nuspec file. - -```choco new testpackage``` - -> :choco-info: **NOTE** -> -> If your package uses recently introduced functionality, you might want to include `chocolatey` as a dependency with the version being the lowest version that has the introduced functionality. Otherwise the installation could fail for users with an older version of `Chocolatey` installed. - -You can indicate the `Chocolatey` dependency like any other dependency. For example: - -```xml - <dependencies> - <dependency id="chocolatey" version="0.9.8.21" /> - </dependencies> -``` - -Logically, the version is based on the lowest compatible version. But if you don't know and used a lot of sorcery in your package, depend on the version of `Chocolatey` that you succesfully tested your package on. - -**See also:** [NuGet Version Reference](http://docs.nuget.org/docs/reference/versioning) - -## How do I Create a New Package? - -- **Generate new package**: - - `choco new -h` will get you started seeing options available to you. - - Once you figured out all of your options, you should move forward with generating your template. - -## Install Only on Some Versions of Windows - -Right now if the software the package installs is only supported on particular versions of Windows, you should absolutely fail the package. An installed package indicates success. If you pass a warning message but don't also throw an error, that means the package installed successfully. Folks using the package are going to be confused because they will then expect that the underlying software is also installed. The software itself may throw a cryptic error, which will lead to questions from the community about why it is broken (when it is just unsupported). Do yourself a favor and check the version of Windows and throw an error if it is not a supported version. Under no circumstances should you bypass with a warning, because a warning is still a success. - -There is at least one noted exception to this and that is low-level packages that are meant as dependencies that need to be present even if they do not install anything. These are things like KBs that only need to be installed on some versions of Windows. If the package failed and it was a dependency of a higher level package that installed software, it would cause issues attempting to install that software on different versions of Windows. Since about 5% of the packages apply to this exception, stick with the above thoughts for packages. - -> :choco-info: **NOTE** -> -> We will ultimately enhance the nuspec and take care of this for you automatically. Until we get there, follow the above avenue. - -## Installation Paths - -As the package maintainer, you decide where the packaged application is installed or extracted to. Depending on your type of application (see _"What distinction does Chocolatey make between an installable and a portable application?"_ at the bottom of the [FAQ](xref:faqs)) there are a couple of suitable locations (not listed in any particular order): - -### 1. The default installation path of your .msi/.exe setup file - -The original creator probably had a reason for choosing a specific default installation path. -If you think, the user should be able to customize this path and you, the package maintainer, know how to pass a custom path on to the installer, then you should use `%ChocolateyBinRoot%`. - -### 2. The Package Directory in `%ChocolateyInstall%\lib\mypackage` - -You can extract the application within the package directory itself (or even ship an extracted version with the package). This allows Chocolatey to automatically find executables and put those on `%path%`. - -### 3. Path Provided by the `Get-ToolsLocation` Helper - -> :choco-warning: **WARNING** -> -> It was previously possible to use the helper `Get-BinRoot` for backwards compatibility. This is still possible in v1.0.0, however its use is not recommended as the function is now deprecated, and will be removed in v2.0.0. - -The path returned by the helper `Get-ToolsLocation` can be used as the parent directory for the installation. `Get-ToolsLocation` will return the value of the environment variable `%ChocolateyToolsLocation%`. If the value does not contain a drive reference, the system drive will be prepended. If the environment variable is not set, the default path (`C:\tools`) will be returned. - -As an example, [GeoServer](https://github.com/AdmiringWorm/chocolatey-packages/blob/0f3b93ab7b067b265a06349a68297d07b1598e64/automatic/geoserver/tools/chocolateyuninstall.ps1#L8) uses `%ChocolateyToolsLocation%`. If the environment variable is not set, it will be set to `c:\tools` and GeoServer will install to `C:\tools\GeoServer` by default. If `%ChocolateyToolsLocation%` is set to "C:\Common\bin", GeoServer installs to `C:\Common\bin\GeoServer`. - -`%ChocolateyToolsLocation%` gives the Chocolatey user a way of controlling where packages are installed. If you want to allow customizing the installation path, then this is currently the way to go. - -### Make it clear in the package description - -No matter how you decide, you are advised to state the default installation directory in your package description. This prevents confusion about where the application will end up being installed. - -If you allow customizing the installation path, then append instructions on how to do that, too. - -### Windows Environment Variables - -Chocolatey installations are advised to be performed while running "as administrator". Because of this it is important that you understand that some windows environment variables will be pinned to the administrator user and not the installation user at least -one circumstance. - -On many systems there are multiple accounts. The issue can occur on a system where there is an admin user with an account type of "Administrator", let's call this user **admin**. There is another user with an account type of "Standard User" lets call this second user **user**. - -> :choco-info: **NOTE** -> -> "Administrator" and "Standard User" are the 2 account types that Windows 10 supports. - -When **admin** chooses to run a `cmd` shell with elevated privileges by right clicking and selecting "Run as administrator". **admin** will be warned by "User Access Control" that they are elevating privileges via a dialog that **admin** can dismiss. The command shell will run the shell with administrator rights from the **admin** account. All good! - -When **user** chooses to run a `cmd` shell by right clicking and selecting "Run as administrator", **user** will be asked to enter the credentials for **admin** account to gain administrator rights. **user** will need to enter **admin**'s credentials and then the command shell will run the shell with administrator rights from the **admin** account. Wait... what? - -Yes, really. An elevated command shell for **user** will run as if it is the **admin** user! - -That means that when your installer depends on any environment variables to find install locations there is a scenario where the environment variables are from a different user (e.g. **admin**) than the user installing the package. - -The known affected environment variables are: `APPDATA`, `LOCALAPPDATA`, `TEMP`, `TMP`, `USERNAME`, `USERPROFILE` - -Example Settings for a user named "administrator": - -``` -APPDATA=C:\Users\administrator\AppData\Roaming -LOCALAPPDATA=C:\Users\administrator\AppData\Local -TEMP=C:\Users\administrator\AppData\Local\Temp -TMP=C:\Users\administrator\AppData\Local\Temp -USERNAME=administrator -USERPROFILE=C:\Users\administrator -``` - -A simple way around this is to ask the user to set environment variables that can override environment variables. Or alternatively, instruct your users to set the necessary environment variables in the elevated privileges command shell. - -Example instructions: - -> Within the administrator command shell you will need to set 2 environment variables: -> -> ``` -> set LOCALAPPDATA=C:\Users\<USERNAME>\AppData\Local -> set USERPROFILE=C:\Users\<USERNAME> -> ``` - -## Upgrading - -Prior to choco version 0.9.10, there is no dedicated automation script for upgrade scenarios. Instead, your [chocolateyInstall.ps1](xref:chocolatey-install-ps1) script should support installing/upgrading on top of any previous versions of your package. - -More recent versions of choco (0.9.10+) give you the option of supplying a `chocolateyBeforeModify.ps1` script. -If applicable, the version of this script from the currently installed package will be run before subsequent -chocolateyInstall or chocolateyUninstall scripts. - -## Uninstalling - -Uninstalling is handled by a `chocolateyUninstall.ps1` script, which should be in your package's `tools` directory, next to [chocolateyInstall.ps1](xref:chocolatey-install-ps1). All the usual [helper reference](xref:powershell-reference) are available. If your package doesn't uninstall cleanly, people will get grumpy because they'll have to manually clean up after you. Be a good human being and write an uninstaller. - -## Dependency Chaining - -You can make packages that depend on other packages just by adding those dependencies to the nuspec. Take a look at [ferventcoder.chocolatey.utilities nuspec](https://github.com/ferventcoder/chocolatey-packages/blob/master/manual/ferventcoder.chocolatey.utilities/ferventcoder.chocolatey.utilities.nuspec). - -## Avoid Folders Named "content" - -Do not use a folder named "content" in your package. NuGet attaches a special meaning to this folder and will not allow you to have dependencies on packages that have content folders without also having a content folder. It's turtles all the way down until we or NuGet removes this limitation. - -## Naming Your Package - -The **title** of your package (`<title>` tag in the nuspec) should be the same as the name of the application. -Follow the official spelling, use upper and lower case and don’t forget the spaces. -Examples of correct package titles are: _Google Chrome_, _CCleaner_, _PuTTY_ and _FileZilla_. -The title will appear on the left side in the package list of the Chocolatey Community Repository, followed by the version. - -There are some guidelines in terms of the package **ID** (`<id>` tag in the nuspec): - -* **Use only lowercase letters**, even if you used uppercase letters in the package title. - (This is considered a guideline because it is correctable in other ways). - Once a package is submitted (even prior moderation), the Chocolatey Community Repository will always show the id with the casing of the first package version. - In addition, changing the casing of the package id may have negative side effects on dependencies (note: this last statement needs verified). -* If the original application name consists of compound words without spaces (CamelCase), just as _MKVToolNix_, _TightVNC_ and _VirtualBox_, the package id’s are simply the same (but **lowercase** of course): `mkvtoolnix`, `tightvnc`, and `virtualbox`. -* If the name of the application contains multiple words separated by spaces, such as _MusicBrainz Picard_ or _Adobe Reader_, replace the spaces with the hyphen-minus character “-” (U+002D), or just omit them. - **Don’t use dots**. - Dots should be used only if the original application name contains dots (for example, _Paint.NET_). - Hence the correct id’s of the previously mentioned applications can be `musicbrainz-picard` or `adobereader`. - We recommended you use the hyphen method when there are long package names to ensure they remain readable. -* For sub-packages, use the hyphen-minus character “-” (U+002D) as the separator, not a dot. - Sub-packages are intended for separate packages that include extensions, modules or additional features/files for other applications. - Therefore `keepass-langfiles` is a proper package id, because it adds the language files for the main application which in this case is _KeePass_. - Another example is `libreoffice-help` for the help pack for _LibreOffice_, the open source office suite. -* If you want to package an open source application, first search for any pre-existing packages on services like [Repology](https://repology.org/). - If there are already published packages for the application on another repository, **use the same package id**. - This will make it easier for users which work with multiple platforms, so they don't have to remember and use different package names. -* Do not use `chocolatey` in your package ID as this indicates an official package. You can use `choco` instead, but you must include the word 'Unofficial' in the package title. - -These guidelines are already commonly applied on packages for all major Linux distributions, because they lead to a more consistent user experience for software repositories, result in easier to remember package IDs, and reduce unnecessary considerations on naming packages for package creators. - -Note that some packages in the Chocolatey Community Repository don't follow these guidelines; many of these were created before these guidelines were introduced. -New packages should follow the guidelines to improve the overall experience for users going forward. - -If you are going to offer a package that has both an installer and an archive (zip or executable only) version of the application, create three packages - see [Portable vs Installable](xref:faqs#what-distinction-does-chocolatey-make-between-an-installable-and-a-portable-application) and [Install, Portable, and Meta/Virtual Packages](xref:faqs#what-is-the-difference-between-packages-no-suffix-as-compared-to.install.portable). - -### Naming Packages to Allow for Side-by-Side Installation - -For some software, it is expected that users may want multiple different versions installed simultaneously. -This has commonly been seen with software like Python which offer some kind of runtime dependency that other scripts or applications depend on. - -In the past, Chocolatey CLI supported a "side-by-side" installation method which could be used for this purpose to install multiple distinct versions side-by-side, on the same machine. -This has been deprecated and is no longer supported in version 2.0.0 due to many issues with the use and implementation of the feature. - -#### If the Software You're Creating a Package for Expects **Side-by-Side Installations of Different Versions** - -1. Create _separate package IDs_ for each major version (or major + minor version, depending on the expectations of users) which include the version number in the ID. - For example, if the package ID would be `python`, the package for major version 2 would be `python2`, or a package for specifically the 2.7 branch might be `python27` or `python2-7`. - These individual versioned packages can be updated as normal, as long as that major and/or minor version is still receiving further updates. -1. Create a [**metapackage**](xref:getting-started#terminology) for the overall product with a package version for each of the versioned packages. - In other words, create another package (this time without a version number in the ID), which contains only a `nuspec` file and add a dependency on the versioned package. - Following the above example for Python, we'd create a package with the ID `python` at version `2.0.0` that takes a dependency on the `python2` package. -1. New versions of the metapackage should be published for "sub-versions" of the dependency package as well. - For example, if Python version `3` is released, we'd create a new version of the `python` package with its version set to `3.0.0`, which depends on a new `python3` package. - -#### If the Software You're Creating a Package for Expects **Side-by-Side Installations of the Same Version** - -A possible example might be where multiple different instances of the software are being installed into different install directories. - -Chocolatey does not currently support this functionality. -This functionality can be mimicked by making use of `--force` to forcibly overwrite an already-installed package and providing an argument or package parameter that the package can use to direct the installation to install into a different directory. -However, Chocolatey will only be aware of the most-recently installed copy of the software, and will only be able to provide updates to that single installation of the software in most cases. -As a result, this particular configuration is not supported. - -A potential workaround for users maintaining their own package repositories is to maintain separate instances of the same package under different package IDs, where each package ships the same software, but is scripted to install to a different directory. -For example, you can create a `python3-localtoolsfolder` and a `python3-programfilesfolder` package which have the same contents, with only slight differences in the parameters passed to the install functions to ensure they install in the desired locations. -The recommended naming conventions here are similar to sub-packages, where the package is named after the primary package ID followed by a dash and a discriminator, likely named after the install location or referencing the purpose of the additional package(s). - -## Package Description and Release Notes - -The `<description>` of the package should contain a short text or at least a few words about the software for which the package is made. Here are a few things that should be respected: - -- The description should always be written in English, even if the packaged software does not provide an UI in English. You can also include the software’s description in its original language, but insert it after the English description. -- The description should not just contain a repetition of the package name. -- It should not just consist of a link where more information can be found. For that purpose there’s already `<projectUrl>`. -- The contents of `<description>` and also `<releaseNotes>` are parsed as Markdown, so don’t insert line breaks in the middle of sentences. Remember to add empty lines to separate paragraphs and add an empty line before a list. - -## Versioning Recommendations - -Versioning can be both simple and complicated. The best recommendation is to use the same versioning that the installable/portable application uses. With Chocolatey you get four version segments. If the application only uses 1, 2 or 3 version segments, follow suit. - -If the 4th segment is used, some folks like to drop the segment altogether and use that as only the package fix notation using one of the notations in the next section. There is no recommendations at this time. - -### Package Fix Version Notation - -Package fix version notation ONLY applies when you are making a fix to the package because the existing version of a package is incorrect in some way. So if the software is `1.1.0`, in a normal scenario the package version should be `1.1.0`. If you find that the `1.1.0` package has an issue and you need to fix the package but keep the same version of the software, that is where package fix version notation comes into play. You would end up with both a `1.1.0` package and a `1.1.0.YYYYMMDD` version of the package. - -> :choco-info: **NOTE** -> -> This doesn't apply to packages on the community feed (aka https://community.chocolatey.org/packages) that are still under review (not yet approved). Please read the instructions given in email for resubmitting the same version. - -If you need to fix an approved package for some reason, you can use the fourth version element (aka segment) for a package fix notation. There are two recommended methods of package fix version notation: - -- **Date (Year/Month/Day)** - Some folks use year month day package fix notation (yyyyMMdd as in 20120627 seen as 1.2.0.20120627) -- Sequential - **Not recommended** - Some folks use sequential numbering (0, then 1, etc as in 0 for no fix, 1 for first fix and so on seen as 1.2.0.0 and 1.2.0.1). - -Date Package Fix Version Notation is recommended because one can ascertain what it is immediately upon seeing it, where sequential is not obvious on sight whether it is part of the software versioning or something special with the package. - -Package fix version notation is only acceptable in the fourth segment. Do not use any of the other segments for package fix notation. If an application only uses 1 or 2 version segments, add zeros into the other segments until you get to the 4th segment (i.e. 1.0.0.20120627). - -When the fourth segment is already used, it is recommended to add two zeroes (00) to the end of the version. Then when you need to fix, you just increment that number. So if the package was ruby and the version was 2.0.0-p353, the package is 2.0.0.35300 (adding the two zeroes at the end). Then a fix would be 2.0.0.35301 and so on. - -> :choco-warning: **WARNING** -> -> If you decide to add a secondary set of numbers to the fourth segment, you MUST ALWAYS include that secondary set of numbers while the other three version segments are the same. The reason - if you fix `.1` to `.100`, then release `.2`, `.100` is greater than `.2` because versioning doesn't look at the ".", only the number in the element. So `100` is greater than `2`. - -## Internationalization and Localization of Packages - -For Chocolatey, internationalization and localization of packages is very important, because it has users from all over the world. Many applications support multiple languages, but they use several different methods to achieve that. Therefore, there is no standard how internationalization/localization has to be integrated into packages. However, here are a few examples of packages that use various techniques. You can use them as inspiration for new packages: - -* The ideal situation is when an application determines the user's system language and automatically installs with that language. Then you don't have to take any action relating to localization, because the application already handles that. Examples of such applications are [VLC Media Player](https://community.chocolatey.org/packages/vlc) and [LibreOffice](https://community.chocolatey.org/packages/libreoffice). -* When an application provides different installers for different languages, you should determine the system language and download the appropriate installer. The package for [Mozilla Firefox](https://community.chocolatey.org/packages/Firefox) ([source code](https://github.com/chocolatey-community/chocolatey-packages/tree/master/automatic/Firefox)) uses this method. -* Sometimes an application installer or executable has already integrated all supported languages, but doesn't automatically select the system language during a silent install. Often you can pass an additional install parameter to select the desired language. This is used for example in the [CCleaner](https://community.chocolatey.org/packages/ccleaner) package ([source code](https://github.com/tonigellida/chocolateyautomaticpackages/tree/master/ccleaner)). -* Some application use separate language files which must be downloaded separately and put somewhere in the application directory. It is best when you create a separate package for the language files. If your package id is `packageid`, then call it `packageid-langfiles`. The [language files package for KeePass](https://community.chocolatey.org/packages/keepass-langfiles) is an example how this can be achieved. - -## Package Icon Guidelines - -If there is an icon which is suitable for your package, you can specify it in the `<iconUrl>` tag in the nuspec. But there are a few things you should consider: - -* **Avoid hotlinking icons from sites where you don’t have control over the file.** If you have a packages repository (recommended), use your own copy of the icon and put it there. -* **Use a static CDN for icon URLs that permits you to serve files hosted in a repository on GitHub.** Some CDN services cache files permanently and it's therefore best to use a specific tag or commit URL, not a branch URL. While we don't make any recommendations about specific services, the more popular ones used by maintainers are [jsDelivr](https://www.jsdelivr.com/), [Statically](https://statically.io/) and [Githack](https://raw.githack.com/). -* **Avoid using GitHub raw links** (`https://raw.githubusercontent.com/...`). They are not intended to be used as CDN. -* **Use the software’s icon if one is available, not the logo.** This blog post explains the difference between logos and icons: http://blog.designcrowd.com/article/353/differences-between-logos-and-icons. If the software of your package doesn’t have an icon, but a logo with text and an image, you can extract the image with your favorite image editor and use that as package icon. An example is [MySQL’s dolphin](https://community.chocolatey.org/packages/mysql). -* **Use package icons with at least 128 pixels in width or height** if available. However, avoid very high resolutions, because this would only unnecessarily increase the page load time. If there are only icons with less than 128 pixels available, choose the icon with the highest resolution you can find without upscaling it. Don’t use low resolution favicons as package icons. -* Use icons with transparent background if available. -* Don’t use distorted or blurry icons. -* The package list in the Chocolatey Community Repository shows the icons with a maximum of 48 pixels in width/height. Application logos with very detailed graphics that are barely visible at that dimension are not suitable as package icons. -* **PNG is the preferred format** for raster package icons. Avoid ICO, GIF and JPEG graphics. -* Good sources for package icons are the official desktop icons of the corresponding application you want to make a package of. The icons can be extracted from the app executables using tools like [BeCyIconGrabber](https://community.chocolatey.org/packages/becyicongrabber). Remember to take the icon with 128 px or more and save it as PNG file. - -The icon shown on the community.chocolatey.org package page is saved, and served, locally to mitigate against cross scripting attacks and to prevent getting _non HTTPS assets_ errors on the website. Sometimes the page loads faster than the image can be served and the default image gets cached and as a result the new package icon may not be shown until you clear the browser cache for community.chocolatey.org and wait 3 hours before reloading the page. - -<a name="how-do-i-exclude-executables-from-getting-batch-redirects"></a> - -## How Do I Exclude Executables from Getting Shims? - -If you have executables in the package or brought into the package folder during PowerShell run and you want to exclude them you need to create an empty file named exactly like (**case sensitive**) the executable with `.ignore` suffixed on the end in the same directory where the executable is or will be. - -Example: In the case of `Bob.exe` you would create a file named `Bob.exe.ignore` and that file would not get a redirect batch link. The Chocolatey package has an example of that. To further expand, `bob.exe.ignore` would not work because it doesn't have the correct casing. - -Here's a great [programmatic example](https://github.com/ferventcoder/chocolatey-packages/blob/6ea7c087bd999d428a564b5d7e236ae998ef72e9/automatic/git.commandline/tools/chocolateyInstall.ps1#L13-L20): - -```powershell -$files = get-childitem $installDir -include *.exe -recurse - -foreach ($file in $files) { - #generate an ignore file - New-Item "$file.ignore" -type file -force | Out-Null -} -``` - -<a name="how-do-i-set-up-batch-redirects-for-applications-that-have-a-gui"></a> -## How do I set up shims for applications that have a GUI? -If you don't want to see a hanging window when you open an application from the command line that was set up with Chocolatey, you want to create a file next to the executable that is named exactly the same (**case sensitive**) with `.gui` suffixed on the end. - -Example: In the case of `Bob.exe` you would create a file named `Bob.exe.gui` and that file would be set up as a GUI application so the window will call it and then move on without waiting for it to finish. Again, `bob.exe.gui` would not work because it doesn't have the correct casing. - -## Build Your Package - -Open a command line in the directory where the nuspec is and type [`choco pack`](xref:choco-command-pack). That's it. - -## Testing Your Package - -> :choco-info: **NOTE** -> -> We strongly suggest the following should be performed in a VM and not on your machine. - -> :choco-info: **NOTE** -> -> Testing your package can be done in the same way as the verifier - take a look at [Chocolatey Verifier Testing](https://github.com/chocolatey-community/chocolatey-test-environment). - -To test the package you just built, open a command line shell and navigate to the directory where the `*.nupkg` file is located. Then type: - -```powershell -choco install packageName --debug --verbose --source . -``` - -This will install the package right out of your source. As you find things you may need to fix, using `--force` (`-f`) will remove and reinstall the package from the updated `*.nupkg`. If you are specifically testing `chocolateyBeforeModify.ps1`, you need to be testing upgrade and uninstall scenarios. You need to install a version of the package with this file **first** as before modify is like uninstall, it runs from the installed package, not the package you are installing (like `chocolateyInstall.ps1` does). - -> :choco-info: **NOTE** -> -> Using Force `--force` (`-f`) should only be done in subsequent testing where you are reinstalling the same package that you've changed and should NOT be used in regular use scenarios. It should definitely not be in scripts. - -> :choco-info: **NOTE** -> -> If you are using a Semver dash in your package version (such as 1.0.0-beta), you will need to use the `--pre` switch or else you will get *Unable to find package* errors from `choco install`. You can also specify `-version 1.0.0-beta` to try to install that exact version. - -`.` points to the current directory. You can specify multiple directories separated by a semicolon; - -When your `nuspec` specifies dependencies that are not in your source, you should add their paths to the source directory. E.g. in the case of Chocolatey itself: - -```xml -<dependencies> - <dependency id="chocolatey" version="0.9.8.20" /> -</dependencies> -``` - -You'll need to append the API path like so: -`--source "'.;https://community.chocolatey.org/api/v2/'"` (note the double quotes bookending the apostrophes here, use `%cd%` in cmd.exe or `$pwd` in Powershell.exe if `.` doesn't resolve). See [passing options with quotes](xref:choco-commands#how-to-pass-options-switches). - -> :choco-info: **NOTE** -> -> If you need to do this, please ensure you run `choco pack` first. This method of passing a source won't work calling a nuspec or nupkg directly as it will override the source passed to the local folder. - -You can also use the `--debug` switch on `choco install` to provide more information. - -> :choco-info: **NOTE** -> -> Do not call install with `.nupkg` - pointing to a file explicitly overrides source. You must call your install with the package name, not the nupkg file and location. You've already specified for choco to look in a local source with `--source "'.;https://community.chocolatey.org/api/v2/'"`. Call `choco install dude --source "'.;https://community.chocolatey.org/api/v2/'"`, not `choco install .\dude.nupkg --source "'.;https://community.chocolatey.org/api/v2/'"`. - -### Alternative Testing Strategy - -You can also type `choco install --force --debug --verbose path/to/nuspec` and choco will build the nupkg and attempt to install it. - -> :choco-info: **NOTE** -> -> This is not recommended if you are passing install arguments or package parameters due to some weirdness, and definitely does not work with passed sources as it need to override that with the local folder once it builds the package. Most likely you will want to stick with the recommended strategy. - -## Push Your Package - -To push your package after you have built and tested it, you type `choco push packageName.nupkg --source sourceLocation` where **packageName.nupkg** is the file name of the nupkg that was built and **sourceLocation** is the location of the source you want to push to (for example, `--source "'https://push.chocolatey.org/'"` for the Chocolatey Community Repository). -You must either have set an API key for the target URL, or provide an API key directly to the `push` command via the `--api-key` option. -For example, if pushing to the Chocolatey Community Repository, you will need to have previously set an API key for `https://push.chocolatey.org/` (`choco apikey add --source "'https://push.chocolatey.org/'" --key "'API_KEY_HERE'"`). -For more information, see the reference documentation for [`choco push`](xref:choco-command-push). - -As of Chocolatey CLI v2.0.0, you can set the `defaultPushSource` configuration value if you frequently push packages to the same source. -For example: `choco config set --name defaultPushSource --value https://push.chocolatey.org/` - -## Automatic Packaging? - -Yes - [Automatic Packaging](xref:automatic-packaging) - -## Becoming a Primary Maintainer of an Existing Package - -See [Package Maintainer Handover](xref:package-maintainer-handover) diff --git a/input/en-us/create/functions/format-filesize.md b/input/en-us/create/functions/format-filesize.md deleted file mode 100644 index 8378271b5a..0000000000 --- a/input/en-us/create/functions/format-filesize.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -Order: 10 -xref: format-filesize -Title: Format-FileSize -Description: Information on Format-FileSize function -RedirectFrom: - - docs/helpers-format-file-size - - docs/helpersformatfilesize ---- - -# Format-FileSize - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Format-FileSize.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -DO NOT USE. Not part of the public API. - -## Syntax - -~~~powershell -Format-FileSize ` - -Size <Double> ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Formats file size into a human readable format. - -## Notes - -This function is not part of the API. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Format-FileSize -Size $fileSizeBytes - -~~~ - -## Inputs - -None - -## Outputs - - - * Returns a string representation of the file size in a more friendly -format based on the passed in bytes. - - -## Parameters - -### -Size <Double> -The size of a file in bytes. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | 0 -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Get-WebFile](xref:get-webfile) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Format-FileSize -Full`. - -View the source for [Format-FileSize](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Format-FileSize.ps1) diff --git a/input/en-us/create/functions/get-checksumvalid.md b/input/en-us/create/functions/get-checksumvalid.md deleted file mode 100644 index a4ab05182a..0000000000 --- a/input/en-us/create/functions/get-checksumvalid.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -Order: 20 -xref: get-checksumvalid -Title: Get-ChecksumValid -Description: Information on Get-ChecksumValid function -RedirectFrom: - - docs/helpers-get-checksum-valid - - docs/helpersgetchecksumvalid ---- - -# Get-ChecksumValid - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChecksumValid.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Checks a file's checksum versus a passed checksum and checksum type. - -## Syntax - -~~~powershell -Get-ChecksumValid ` - -File <String> ` - [-Checksum <String>] ` - [-ChecksumType <String>] ` - [-OriginalUrl <String>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Makes a determination if a file meets an expected checksum signature. -This function is usually used when comparing a file that is downloaded -from an official distribution point. If the checksum fails to match the -expected output, this function throws an error. - -Checksums have been used for years as a means of verification. A -checksum hash is a unique value or signature that corresponds to the -contents of a file. File names and extensions can be altered without -changing the checksum signature. However if you changed the contents of -the file, even one character, the checksum will be different. - -Checksums are used to provide as a means of cryptographically ensuring -the contents of a file have not been changed. While some cryptographic -algorithms, including MD5 and SHA1, are no longer considered secure -against attack, the goal of a checksum algorithm is to make it -extremely difficult (near impossible with better algorithms) to alter -the contents of a file (whether by accident or for malicious reasons) -and still result in the same checksum signature. - -When verifying a checksum using a secure algorithm, if the checksum -matches the expected signature, the contents of the file are identical -to what is expected. - -## Notes - -This uses the checksum.exe tool available separately at -https://community.chocolatey.org/packages/checksum. - -Options that affect checksum verification: - -* `--ignore-checksums` - skips checksumming -* `--allow-empty-checksums` - skips checksumming when the package is missing a checksum -* `--allow-empty-checksums-secure` - skips checksumming when the package is missing a checksum for secure (HTTPS) locations -* `--require-checksums` - requires checksums for both non-secure and secure locations -* `--download-checksum`, `--download-checksum-type` - allows user to pass their own checksums -* `--download-checksum-x64`, `--download-checksum-type-x64` - allows user to pass their own checksums - -Features that affect checksum verification: - -* `checksumFiles` - when turned off, skips checksumming -* `allowEmptyChecksums` - when turned on, skips checksumming when the package is missing a checksum -* `allowEmptyChecksumsSecure` - when turned on, skips checksumming when the package is missing a checksum for secure (HTTPS) locations - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-ChecksumValid -File $fileFullPath -CheckSum $checksum -ChecksumType $checksumType - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -File <String> -The full path to a binary file that is checksummed and compared to the -passed Checksum parameter value. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Checksum [<String>] -The expected checksum hash value of the File resource. The checksum -type is covered by ChecksumType. - -> :choco-info: **NOTE** -> -> Checksums in packages are meant as a measure to validate the -originally intended file that was used in the creation of a package is -the same file that is received at a future date. Since this is used for -other steps in the process related to the [community repository](https://community.chocolatey.org/packages), it -ensures that the file a user receives is the same file a maintainer -and a moderator (if applicable), plus any moderation review has -intended for you to receive with this package. If you are looking at a -remote source that uses the same url for updates, you will need to -ensure the package also stays updated in line with those remote -resource updates. You should look into [automatic packaging](xref:automatic-packaging) -to help provide that functionality. - -> :choco-info: **NOTE** -> -> To determine checksums, you can get that from the original -site if provided. You can also use the [checksum tool available on -the community feed](https://community.chocolatey.org/packages/checksum) (`choco install checksum`) -and use it e.g. `checksum -t sha256 -f path\to\file`. Ensure you -provide checksums for all remote resources used. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -ChecksumType [<String>] -The type of checksum that the file is validated with - 'md5', 'sha1', -'sha256' or 'sha512' - defaults to 'md5'. - -MD5 is not recommended as certain organizations need to use FIPS -compliant algorithms for hashing - see -https://support.microsoft.com/en-us/kb/811833 for more details. - -The recommendation is to use at least SHA256. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | md5 -Accept Pipeline Input? | false - -### -OriginalUrl [<String>] -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Get-ChocolateyWebFile](xref:get-chocolateywebfile) - * [Install-ChocolateyPackage](xref:install-chocolateypackage) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-ChecksumValid -Full`. - -View the source for [Get-ChecksumValid](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChecksumValid.ps1) diff --git a/input/en-us/create/functions/get-chocolateyconfigvalue.md b/input/en-us/create/functions/get-chocolateyconfigvalue.md deleted file mode 100644 index 2d383ebf09..0000000000 --- a/input/en-us/create/functions/get-chocolateyconfigvalue.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -Order: 30 -xref: get-chocolateyconfigvalue -Title: Get-ChocolateyConfigValue -Description: Information on Get-ChocolateyConfigValue function -RedirectFrom: - - docs/helpers-get-chocolatey-config-value - - docs/helpersgetchocolateyconfigvalue ---- - -# Get-ChocolateyConfigValue - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChocolateyConfigValue.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Retrieve a value from the Chocolatey Configuration file - -## Syntax - -~~~powershell -Get-ChocolateyConfigValue ` - -ConfigKey <String> ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This function will attempt to retrieve the path according to the specified Path Type -to a valid location that can be used by maintainers in certain scenarios. - -## Notes - -Available in 2.1.0+ - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -$value = Get-ChocolateyConfigValue -configKey 'cacheLocation' -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -ConfigKey <String> -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-ChocolateyConfigValue -Full`. - -View the source for [Get-ChocolateyConfigValue](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChocolateyConfigValue.ps1) diff --git a/input/en-us/create/functions/get-chocolateypath.md b/input/en-us/create/functions/get-chocolateypath.md deleted file mode 100644 index 09972304c9..0000000000 --- a/input/en-us/create/functions/get-chocolateypath.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -Order: 40 -xref: get-chocolateypath -Title: Get-ChocolateyPath -Description: Information on Get-ChocolateyPath function -RedirectFrom: - - docs/helpers-get-chocolatey-path - - docs/helpersgetchocolateypath ---- - -# Get-ChocolateyPath - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChocolateyPath.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Retrieve the paths available to be used by maintainers of packages. - -## Syntax - -~~~powershell -Get-ChocolateyPath ` - -PathType <String> [<CommonParameters>] -~~~ - -## Description - -This function will attempt to retrieve the path according to the specified Path Type -to a valid location that can be used by maintainers in certain scenarios. - -## Notes - -Available in 1.2.0+. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -$path = Get-ChocolateyPath -PathType 'PackagePath' -~~~ - -## Inputs - -None - -## Outputs - - - * This function outputs the full path stored accordingly with specified path type. -If no path could be found, there is no output. - - -## Parameters - -### -PathType <String> -The type of path that should be looked up. -Available values are: -- `PackagePath` - The path to the the package that is being installed. Typically `C:\ProgramData\chocolatey\lib\<PackageName>` -- `InstallPath` - The path to where Chocolatey is installed. Typically `C:\ProgramData\chocolatey` - -Property | Value ----------------------- | ----- -Aliases | type -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-ChocolateyPath -Full`. - -View the source for [Get-ChocolateyPath](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChocolateyPath.ps1) diff --git a/input/en-us/create/functions/get-chocolateyunzip.md b/input/en-us/create/functions/get-chocolateyunzip.md deleted file mode 100644 index 23dc868c8d..0000000000 --- a/input/en-us/create/functions/get-chocolateyunzip.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -Order: 50 -xref: get-chocolateyunzip -Title: Get-ChocolateyUnzip -Description: Information on Get-ChocolateyUnzip function -RedirectFrom: - - docs/helpers-get-chocolatey-unzip - - docs/helpersgetchocolateyunzip ---- - -# Get-ChocolateyUnzip - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChocolateyUnzip.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Unzips an archive file and returns the location for further processing. - -## Syntax - -~~~powershell -Get-ChocolateyUnzip ` - [-FileFullPath <String>] ` - -Destination <String> ` - [-SpecificFolder <String>] ` - [-PackageName <String>] ` - [-FileFullPath64 <String>] ` - [-DisableLogging] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This unzips files using the 7-zip command line tool 7z.exe. -Supported archive formats are listed at: -https://sevenzip.osdn.jp/chm/general/formats.htm - -## Notes - -If extraction fails, an exception is thrown. - -If you are embedding files into a package, ensure that you have the -rights to redistribute those files if you are sharing this package -publicly (like on the [community feed](https://community.chocolatey.org/packages)). Otherwise, please use -Install-ChocolateyZipPackage to download those resources from their -official distribution points. - -Will automatically call Set-PowerShellExitCode to set the package exit code -based on 7-zip's exit code. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -# Path to the folder where the script is executing -$toolsDir = (Split-Path -parent $MyInvocation.MyCommand.Definition) -Get-ChocolateyUnzip -FileFullPath "c:\someFile.zip" -Destination $toolsDir -~~~ - -## Inputs - -None - -## Outputs - - - * Returns the passed in $destination. - - -## Parameters - -### -FileFullPath [<String>] -This is the full path to the zip file. If embedding it in the package -next to the install script, the path will be like -`"$(Split-Path -Parent $MyInvocation.MyCommand.Definition)\\file.zip"` - -`File` is an alias for FileFullPath. - -This can be a 32-bit or 64-bit file. This is mandatory in earlier versions -of Chocolatey, but optional if FileFullPath64 has been provided. - -Property | Value ----------------------- | ----- -Aliases | file -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Destination <String> -This is a directory where you would like the unzipped files to end up. -If it does not exist, it will be created. - -Property | Value ----------------------- | ------------- -Aliases | unzipLocation -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -SpecificFolder [<String>] -OPTIONAL - This is a specific directory within zip file to extract. The -folder and its contents will be extracted to the destination. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### -PackageName [<String>] -OPTIONAL - This will facilitate logging unzip activity for subsequent -uninstalls - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### -FileFullPath64 [<String>] -Full file path to a 64-bit native installer to run. -If embedding in the package, you can get it to the path with -`"$(Split-Path -parent $MyInvocation.MyCommand.Definition)\\INSTALLER_FILE"` - -Provide this when you want to provide both 32-bit and 64-bit -installers or explicitly only a 64-bit installer (which will cause a package -install failure on 32-bit systems). - -Property | Value ----------------------- | ------ -Aliases | file64 -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -DisableLogging -OPTIONAL - This disables logging of the extracted items. It speeds up -extraction of archives with many files. - -Usage of this parameter will prevent Uninstall-ChocolateyZipPackage -from working, extracted files will have to be cleaned up with -Remove-Item or a similar command instead. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyZipPackage](xref:install-chocolateyzippackage) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-ChocolateyUnzip -Full`. - -View the source for [Get-ChocolateyUnzip](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChocolateyUnzip.ps1) diff --git a/input/en-us/create/functions/get-chocolateywebfile.md b/input/en-us/create/functions/get-chocolateywebfile.md deleted file mode 100644 index 70aa827bcf..0000000000 --- a/input/en-us/create/functions/get-chocolateywebfile.md +++ /dev/null @@ -1,344 +0,0 @@ ---- -Order: 60 -xref: get-chocolateywebfile -Title: Get-ChocolateyWebFile -Description: Information on Get-ChocolateyWebFile function -RedirectFrom: - - docs/helpers-get-chocolatey-web-file - - docs/helpersgetchocolateywebfile ---- - -# Get-ChocolateyWebFile - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChocolateyWebFile.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Downloads a file from the internet. - -## Syntax - -~~~powershell -Get-ChocolateyWebFile ` - -PackageName <String> ` - -FileFullPath <String> ` - [-Url <String>] ` - [-Url64bit <String>] ` - [-Checksum <String>] ` - [-ChecksumType <String>] ` - [-Checksum64 <String>] ` - [-ChecksumType64 <String>] ` - [-Options <Hashtable>] ` - [-GetOriginalFileName] ` - [-ForceDownload] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This will download a file from a url, tracking with a progress bar. -It returns the filepath to the downloaded file when it is complete. - -## Notes - -Chocolatey works best when the packages contain the software it is -managing and doesn't require downloads. However most software in the -Windows world requires redistribution rights and when sharing packages -publicly (like on the [community feed](https://community.chocolatey.org/packages)), maintainers may not have those -aforementioned rights. Chocolatey understands how to work with that, -hence this function. You are not subject to this limitation with -internal packages. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-ChocolateyWebFile '__NAME__' 'C:\somepath\somename.exe' 'URL' '64BIT_URL_DELETE_IF_NO_64BIT' - -~~~ - -**EXAMPLE 2** - -~~~powershell - -# Download from an HTTPS location -$toolsDir = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)" -Get-ChocolateyWebFile -PackageName 'bob' -FileFullPath "$toolsDir\bob.exe" -Url 'https://somewhere/bob.exe' -~~~ - -**EXAMPLE 3** - -~~~powershell - -# Download from FTP -$toolsDir = "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)" -Get-ChocolateyWebFile -PackageName 'bob' -FileFullPath "$toolsDir\bob.exe" -Url 'ftp://somewhere/bob.exe' -~~~ - -**EXAMPLE 4** - -~~~powershell - -# Download from a file share -$toolsDir = "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)" -Get-ChocolateyWebFile -PackageName 'bob' -FileFullPath "$toolsDir\bob.exe" -Url 'file:///\\fileshare\location\bob.exe' -~~~ - -**EXAMPLE 5** - -~~~powershell - -$options = -@{ - Headers = @{ - Accept = 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8'; - 'Accept-Charset' = 'ISO-8859-1,utf-8;q=0.7,*;q=0.3'; - 'Accept-Language' = 'en-GB,en-US;q=0.8,en;q=0.6'; - Cookie = 'requiredinfo=info'; - Referer = 'https://somelocation.com/'; - } -} - -Get-ChocolateyWebFile -PackageName 'package' -FileFullPath "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)\thefile.exe" -Url 'https://somelocation.com/thefile.exe' -Options $options -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -PackageName <String> -The name of the package - while this is an arbitrary value, it's -recommended that it matches the package id. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -FileFullPath <String> -This is the full path of the resulting file name. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -Url [<String>] -This is the 32 bit url to download the resource from. This resource can -be used on 64 bit systems when a package has both a Url and Url64bit -specified if a user passes `--forceX86`. If there is only a 64 bit url -available, please remove do not use the parameter (only use Url64bit). -Will fail on 32bit systems if missing or if a user attempts to force -a 32 bit installation on a 64 bit system. - -Prefer HTTPS when available. Can be HTTP, FTP, or File URIs. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### -Url64bit [<String>] -OPTIONAL - If there is a 64 bit resource available, use this -parameter. Chocolatey will automatically determine if the user is -running a 64 bit OS or not and adjust accordingly. Please note that -the 32 bit url will be used in the absence of this. This parameter -should only be used for 64 bit native software. If the original Url -contains both (which is quite rare), set this to '$url' Otherwise -remove this parameter. - -Prefer HTTPS when available. Can be HTTP, FTP, or File URIs. - -`Url64` is an alias for Url64bit. - -Property | Value ----------------------- | ----- -Aliases | url64 -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### -Checksum [<String>] -The checksum hash value of the Url resource. This allows a checksum to -be validated for files that are not local. The checksum type is covered -by ChecksumType. - -> :choco-info: **NOTE** -> -> Checksums in packages are meant as a measure to validate the -originally intended file that was used in the creation of a package is -the same file that is received at a future date. Since this is used for -other steps in the process related to the [community repository](https://community.chocolatey.org/packages), it -ensures that the file a user receives is the same file a maintainer -and a moderator (if applicable), plus any moderation review has -intended for you to receive with this package. If you are looking at a -remote source that uses the same url for updates, you will need to -ensure the package also stays updated in line with those remote -resource updates. You should look into [automatic packaging](xref:automatic-packaging) -to help provide that functionality. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ChecksumType [<String>] -The type of checksum that the file is validated with - valid -values are 'md5', 'sha1', 'sha256' or 'sha512' - defaults to 'md5'. - -MD5 is not recommended as certain organizations need to use FIPS -compliant algorithms for hashing - see -https://support.microsoft.com/en-us/kb/811833 for more details. - -The recommendation is to use at least SHA256. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Checksum64 [<String>] -OPTIONAL if no Url64bit - The checksum hash value of the Url64bit -resource. This allows a checksum to be validated for files that are not -local. The checksum type is covered by ChecksumType64. - -> :choco-info: **NOTE** -> -> Checksums in packages are meant as a measure to validate the -originally intended file that was used in the creation of a package is -the same file that is received at a future date. Since this is used for -other steps in the process related to the [community repository](https://community.chocolatey.org/packages), it -ensures that the file a user receives is the same file a maintainer -and a moderator (if applicable), plus any moderation review has -intended for you to receive with this package. If you are looking at a -remote source that uses the same url for updates, you will need to -ensure the package also stays updated in line with those remote -resource updates. You should look into [automatic packaging](xref:automatic-packaging) -to help provide that functionality. - -> :choco-info: **NOTE** -> -> To determine checksums, you can get that from the original -site if provided. You can also use the [checksum tool available on -the community feed](https://community.chocolatey.org/packages/checksum) (`choco install checksum`) -and use it e.g. `checksum -t sha256 -f path\to\file`. Ensure you -provide checksums for all remote resources used. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ChecksumType64 [<String>] -OPTIONAL - The type of checksum that the file is validated with - valid -values are 'md5', 'sha1', 'sha256' or 'sha512' - defaults to -ChecksumType parameter value. - -MD5 is not recommended as certain organizations need to use FIPS -compliant algorithms for hashing - see -https://support.microsoft.com/en-us/kb/811833 for more details. - -The recommendation is to use at least SHA256. - -Property | Value ----------------------- | ------------- -Aliases | -Required? | false -Position? | named -Default Value | $checksumType -Accept Pipeline Input? | false - -### -Options [<Hashtable>] -OPTIONAL - Specify custom headers. - -Property | Value ----------------------- | ----------------- -Aliases | -Required? | false -Position? | named -Default Value | @{Headers = @{} } -Accept Pipeline Input? | false - -### -GetOriginalFileName -OPTIONAL switch to allow Chocolatey to determine the original file name -from the url resource. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -ForceDownload -OPTIONAL switch to force download of file every time, even if the file -already exists. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyPackage](xref:install-chocolateypackage) - * [Get-WebFile](xref:get-webfile) - * [Get-WebFileName](xref:get-webfilename) - * [Get-FtpFile](xref:get-ftpfile) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-ChocolateyWebFile -Full`. - -View the source for [Get-ChocolateyWebFile](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChocolateyWebFile.ps1) diff --git a/input/en-us/create/functions/get-ftpfile.md b/input/en-us/create/functions/get-ftpfile.md deleted file mode 100644 index a3fa9df94e..0000000000 --- a/input/en-us/create/functions/get-ftpfile.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -Order: 90 -xref: get-ftpfile -Title: Get-FtpFile -Description: Information on Get-FtpFile function -RedirectFrom: - - docs/helpers-get-ftp-file - - docs/helpersgetftpfile ---- - -# Get-FtpFile - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-FtpFile.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Downloads a file from a File Transfer Protocol (FTP) location. - -## Syntax - -~~~powershell -Get-FtpFile ` - [-Url <String>] ` - -FileName <String> ` - [-Username <String>] ` - [-Password <String>] ` - [-Quiet] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This will download a file from an FTP location, saving the file to the -FileName location specified. - -## Notes - -This is a low-level function and not recommended for use in package -scripts. It is recommended you call `Get-ChocolateyWebFile` instead. - -Will automatically call Set-PowerShellExitCode to set the package -exit code to 404 if the resource is not found. - -## Aliases - -None - -## Inputs - -None - -## Outputs - - - * None - - -## Parameters - -### -Url [<String>] -This is the url to download the file from. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -FileName <String> -This is the full path to the file to create. If FTPing to the -package folder next to the install script, the path will be like -`"$(Split-Path -Parent $MyInvocation.MyCommand.Definition)\\file.exe"` - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -Username [<String>] -The user account to connect to FTP with. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### -Password [<String>] -The password for the user account on the FTP server. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### -Quiet -Silences the progress output. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Get-ChocolateyWebFile](xref:get-chocolateywebfile) - * [Get-WebFile](xref:get-webfile) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-FtpFile -Full`. - -View the source for [Get-FtpFile](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-FtpFile.ps1) diff --git a/input/en-us/create/functions/get-osarchitecturewidth.md b/input/en-us/create/functions/get-osarchitecturewidth.md deleted file mode 100644 index 714a0ad5be..0000000000 --- a/input/en-us/create/functions/get-osarchitecturewidth.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -Order: 100 -xref: get-osarchitecturewidth -Title: Get-OSArchitectureWidth -Description: Information on Get-OSArchitectureWidth function -RedirectFrom: - - docs/helpers-get-os-architecture-width - - docs/helpersgetosarchitecturewidth - - docs/helpers-get-o-s-architecture-width ---- - -# Get-OSArchitectureWidth - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-OSArchitectureWidth.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Get the operating system architecture address width. - -## Syntax - -~~~powershell -Get-OSArchitectureWidth ` - [-Compare <Object>] -~~~ - -## Description - -This will return the system architecture address width (probably 32 or -64 bit). If you pass a comparison, it will return true or false instead -of {`32`|`64`}. - -## Notes - -When your installation script has to know what architecture it is run -on, this simple function comes in handy. - -ARM64 architecture will automatically select 32bit width as -there is an emulator for 32 bit and there are no current plans by Microsoft to -ship 64 bit x86 emulation for ARM64. For more details, see -https://github.com/chocolatey/choco/issues/1800#issuecomment-484293844. - -## Aliases - -`Get-OSBitness` -`Get-ProcessorBits` - - -## Inputs - -None - -## Outputs - -None - - -## Parameters - -### -Compare [<Object>] -This optional parameter causes the function to return $true or $false, -depending on whether or not the bit width matches. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-OSArchitectureWidth -Full`. - -View the source for [Get-OSArchitectureWidth](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-OSArchitectureWidth.ps1) diff --git a/input/en-us/create/functions/get-packageparameters.md b/input/en-us/create/functions/get-packageparameters.md deleted file mode 100644 index f013c1ad6b..0000000000 --- a/input/en-us/create/functions/get-packageparameters.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -Order: 110 -xref: get-packageparameters -Title: Get-PackageParameters -Description: Information on Get-PackageParameters function -RedirectFrom: - - docs/helpers-get-package-parameters - - docs/helpersgetpackageparameters - - docs/helpers-get-packageparameters ---- - -# Get-PackageParameters - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-PackageParameters.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Parses a string and returns a hash table array of those values for use -in package scripts. - -## Syntax - -~~~powershell -Get-PackageParameters ` - [-Parameters <String>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This looks at a string value and parses it into a hash table array for -use in package scripts. By default this will look at -`$env:ChocolateyPackageParameters` (`--params="'/ITEM:value'"`) and -`$env:ChocolateyPackageParametersSensitive` -(`--package-parameters-sensitive="'/PASSWORD:value'"` in commercial -editions). - -[Learn more](xref:parse-package-parameters) - -## Notes - -If you need compatibility with older versions of Chocolatey, -take a dependency on the `chocolatey-core.extension` package which -also provides this functionality. If you are pushing to the community -package repository (https://community.chocolatey.org/packages), you are required -to take a dependency on the core extension until January 2018. How to -do this is explained in [the docs](xref:parse-package-parameters#step-3-use-core-community-extension). - -The differences between this and the `chocolatey-core.extension` package -functionality is that the extension function can only do one string at a -time and it only looks at `$env:ChocolateyPackageParameters` by default. -It also only supports splitting by `:`, with this function you can -either split by `:` or `=`. For compatibility with the core extension, -build all docs with `/Item:Value`. - -## Aliases - -`Get-PackageParametersBuiltIn` - - -## Examples - - **EXAMPLE 1** - -~~~powershell - -# The default way of calling, uses `$env:ChocolateyPackageParameters` -# and `$env:ChocolateyPackageParametersSensitive` - this is typically -# how things are passed in from choco.exe -$pp = Get-PackageParameters -~~~ - -**EXAMPLE 2** - -~~~powershell - -# see https://docs.chocolatey.org/en-us/guides/create/parse-packageparameters-argument -# command line call: `choco install <pkg_id> --params "'/LICENSE:value'"` -$pp = Get-PackageParameters -# Read-Host, PromptForChoice, etc are not blocking calls with Chocolatey. -# Chocolatey has a custom PowerShell host that will time these calls -# after 30 seconds, allowing headless operation to continue but offer -# prompts to users to ask questions during installation. -if (!$pp['LICENSE']) { $pp['LICENSE'] = Read-Host 'License key?' } -# set a default if not passed -if (!$pp['LICENSE']) { $pp['LICENSE'] = '1234' } -~~~ - -**EXAMPLE 3** - -~~~powershell - -$pp = Get-PackageParameters -if (!$pp['UserName']) { $pp['UserName'] = "$env:UserName" } -if (!$pp['Password']) { $pp['Password'] = Read-Host "Enter password for $($pp['UserName']):" -AsSecureString} -# fail the install/upgrade if not value is not determined -if (!$pp['Password']) { throw "Package needs Password to install, that must be provided in params or in prompt." } -~~~ - -**EXAMPLE 4** - -~~~powershell - -# Pass in your own values -Get-PackageParameters -Parameters "/Shortcut /InstallDir:'c:\program files\xyz' /NoStartup" | set r -if ($r.Shortcut) {... } -Write-Host $r.InstallDir -~~~ - -## Inputs - -None - -## Outputs - - - * [HashTable] - - -## Parameters - -### -Parameters [<String>] -OPTIONAL - Specify a string to parse. If not set, will use -`$env:ChocolateyPackageParameters` and -`$env:ChocolateyPackageParametersSensitive` to parse values from. - -Parameters should be passed as "/NAME:value" or "/NAME=value". For -compatibility with `chocolatey-core.extension`, use `:`. - -For example `-Parameters "/ITEM1:value /ITEM2:value with spaces" - -Property | Value ----------------------- | ------ -Aliases | params -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply and future expansion. -Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyPackage](xref:install-chocolateypackage) - * [Install-ChocolateyInstallPackage](xref:install-chocolateyinstallpackage) - * [Install-ChocolateyZipPackage](xref:install-chocolateyzippackage) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-PackageParameters -Full`. - -View the source for [Get-PackageParameters](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-PackageParameters.ps1) diff --git a/input/en-us/create/functions/get-toolslocation.md b/input/en-us/create/functions/get-toolslocation.md deleted file mode 100644 index 6a05567090..0000000000 --- a/input/en-us/create/functions/get-toolslocation.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -Order: 120 -xref: get-toolslocation -Title: Get-ToolsLocation -Description: Information on Get-ToolsLocation function -RedirectFrom: - - docs/helpers-get-tools-location - - docs/helpersgettoolslocation ---- - -# Get-ToolsLocation - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ToolsLocation.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Gets the top level location for tools/software installed outside of -package folders. - -## Syntax - -~~~powershell -Get-ToolsLocation -~~~ - -## Description - -Creates or uses an environment variable that a user can control to -communicate with packages about where they would like software that is -not installed through native installers, but doesn't make much sense -to be kept in package folders. Most software coming in packages stays -with the package itself, but there are some things that seem to fall -out of this category, like things that have plugins that are installed -into the same directory as the tool. Having that all combined in the -same package directory could get tricky. - -## Notes - -Sets an environment variable called `ChocolateyToolsLocation`. If the -older `ChocolateyBinRoot` is set, it uses the value from that and -removes the older variable. - -## Aliases - -`Get-BinRoot` - - -## Inputs - -None - -## Outputs - -None - -## Parameters - - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-ToolsLocation -Full`. - -View the source for [Get-ToolsLocation](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ToolsLocation.ps1) diff --git a/input/en-us/create/functions/get-uacenabled.md b/input/en-us/create/functions/get-uacenabled.md deleted file mode 100644 index e34b085d24..0000000000 --- a/input/en-us/create/functions/get-uacenabled.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -Order: 130 -xref: get-uacenabled -Title: Get-UACEnabled -Description: Information on Get-UACEnabled function -RedirectFrom: - - docs/helpers-get-uac-enabled - - docs/helpersgetuacenabled ---- - -# Get-UACEnabled - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-UACEnabled.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Determines if UAC (User Account Control) is turned on or off. - -## Syntax - -~~~powershell -Get-UACEnabled -~~~ - -## Description - -This is a low level function used by Chocolatey to decide whether -prompting for elevated privileges is necessary or not. - -## Notes - -This checks the `EnableLUA` registry value to be determine the state of -a system. - -## Aliases - -None - -## Inputs - -None - -## Outputs - - - * System.Boolean - - -## Parameters - - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-UACEnabled -Full`. - -View the source for [Get-UACEnabled](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-UACEnabled.ps1) diff --git a/input/en-us/create/functions/get-uninstallregistrykey.md b/input/en-us/create/functions/get-uninstallregistrykey.md deleted file mode 100644 index a8442a49fe..0000000000 --- a/input/en-us/create/functions/get-uninstallregistrykey.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -Order: 140 -xref: get-uninstallregistrykey -Title: Get-UninstallRegistryKey -Description: Information on Get-UninstallRegistryKey function -RedirectFrom: - - docs/helpers-get-uninstall-registry-key - - docs/helpersgetuninstallregistrykey ---- - -# Get-UninstallRegistryKey - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-UninstallRegistryKey.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Retrieve registry key(s) for system-installed applications from an -exact or wildcard search. - -## Syntax - -~~~powershell -Get-UninstallRegistryKey ` - -SoftwareName <String> ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This function will attempt to retrieve a matching registry key for an -already installed application, usually to be used with a -chocolateyUninstall.ps1 automation script. - -The function also prevents `Get-ItemProperty` from failing when -handling wrongly encoded registry keys. - - -## Aliases - -`Get-InstallRegistryKey` - - -## Examples - - **EXAMPLE 1** - -~~~powershell - -# Version match: Software name is "Gpg4Win (2.3.0)" -[array]$key = Get-UninstallRegistryKey -SoftwareName "Gpg4win (*)" -$key.UninstallString -~~~ - -**EXAMPLE 2** - -~~~powershell - -# Fuzzy match: Software name is "Launchy 2.5" -[array]$key = Get-UninstallRegistryKey -SoftwareName "Launchy*" -$key.UninstallString -~~~ - -**EXAMPLE 3** - -~~~powershell - -# Exact match: Software name in Programs and Features is "VLC media player" -[array]$key = Get-UninstallRegistryKey -SoftwareName "VLC media player" -$key.UninstallString -~~~ - -**EXAMPLE 4** - -~~~powershell - -# Version match: Software name is "SketchUp 2016" -# Note that the similar software name "SketchUp Viewer" would not be matched. -[array]$key = Get-UninstallRegistryKey -SoftwareName "SketchUp [0-9]*" -$key.UninstallString -~~~ - -## Inputs - -None - -## Outputs - - - * This function searches registry objects and returns an array -of PSCustomObject with the matched key's properties. - * Retrieve properties with dot notation, for example: -`$key.UninstallString` - - -## Parameters - -### -SoftwareName <String> -Part or all of the Display Name as you see it in Programs and Features. -It should be enough to be unique. -The syntax follows the rules of the PowerShell `-like` operator, so the -`*` character is interpreted as a wildcard, which matches any (zero or -more) characters. - -If the display name contains a version number, such as "Launchy (2.5)", -it is recommended you use a fuzzy search `"Launchy (*)"` (the wildcard -`*`) so if Launchy auto-updates or is updated outside of Chocolatey, the -uninstall script will not fail. - -Take care not to abuse fuzzy/glob pattern searches. Be conscious of -programs that may have shared or common root words to prevent -overmatching. For example, "SketchUp*" would match two keys with -software names "SketchUp 2016" and "SketchUp Viewer" that are different -programs released by the same company. - -Property | Value ----------------------- | -------------- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | true (ByValue) - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyPackage](xref:install-chocolateypackage) - * [Install-ChocolateyInstallPackage](xref:install-chocolateyinstallpackage) - * [Uninstall-ChocolateyPackage](xref:uninstall-chocolateypackage) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-UninstallRegistryKey -Full`. - -View the source for [Get-UninstallRegistryKey](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-UninstallRegistryKey.ps1) diff --git a/input/en-us/create/functions/get-viruscheckvalid.md b/input/en-us/create/functions/get-viruscheckvalid.md deleted file mode 100644 index 299a83a35e..0000000000 --- a/input/en-us/create/functions/get-viruscheckvalid.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -Order: 150 -xref: get-viruscheckvalid -Title: Get-VirusCheckValid -Description: Information on Get-VirusCheckValid function -RedirectFrom: - - docs/helpers-get-virus-check-valid - - docs/helpersgetviruscheckvalid ---- - -# Get-VirusCheckValid - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-VirusCheckValid.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Used in Pro/Business editions. Runtime virus check against downloaded -resources. - -## Syntax - -~~~powershell -Get-VirusCheckValid ` - [-Url <String>] ` - [-File <String>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Run a runtime malware check against downloaded resources prior to -allowing Chocolatey to execute a file. This is only available -in Pro / Business editions. - -## Notes - -Only [licensed editions](https://chocolatey.org/compare) of Chocolatey provide runtime malware protection. - -## Aliases - -None - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Url [<String>] -Not used - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -File [<String>] -The full file path to the file to verify against anti-virus scanners. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-VirusCheckValid -Full`. - -View the source for [Get-VirusCheckValid](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-VirusCheckValid.ps1) diff --git a/input/en-us/create/functions/get-webfile.md b/input/en-us/create/functions/get-webfile.md deleted file mode 100644 index 4ef8858fcd..0000000000 --- a/input/en-us/create/functions/get-webfile.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -Order: 160 -xref: get-webfile -Title: Get-WebFile -Description: Information on Get-WebFile function -RedirectFrom: - - docs/helpers-get-web-file - - docs/helpersgetwebfile ---- - -# Get-WebFile - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-WebFile.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Downloads a file from an HTTP/HTTPS location. Prefer HTTPS when -available. - -## Syntax - -~~~powershell -Get-WebFile ` - [-Url <String>] ` - [-FileName <String>] ` - [-UserAgent <String>] ` - [-Passthru] ` - [-Quiet] ` - [-Options <Hashtable>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This will download a file from an HTTP/HTTPS location, saving the file -to the FileName location specified. - -## Notes - -This is a low-level function and not recommended for use in package -scripts. It is recommended you call `Get-ChocolateyWebFile` instead. - -Will automatically call Set-PowerShellExitCode to set the package exit -code to 404 if the resource is not found. - -## Aliases - -None - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Url [<String>] -This is the url to download the file from. Prefer HTTPS when available. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -FileName [<String>] -This is the full path to the file to create. If downloading to the -package folder next to the install script, the path will be like -`"$(Split-Path -Parent $MyInvocation.MyCommand.Definition)\\file.exe"` - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -UserAgent [<String>] -The user agent to use as part of the request. Defaults to 'chocolatey -command line'. - -Property | Value ----------------------- | ----------------------- -Aliases | -Required? | false -Position? | 3 -Default Value | chocolatey command line -Accept Pipeline Input? | false - -### -Passthru -DO NOT USE - holdover from original function. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -Quiet -Silences the progress output. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -Options [<Hashtable>] -OPTIONAL - Specify custom headers. - -Property | Value ----------------------- | ----------------- -Aliases | -Required? | false -Position? | named -Default Value | @{Headers = @{} } -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Get-ChocolateyWebFile](xref:get-chocolateywebfile) - * [Get-FtpFile](xref:get-ftpfile) - * [Get-WebHeaders](xref:get-webheaders) - * [Get-WebFileName](xref:get-webfilename) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-WebFile -Full`. - -View the source for [Get-WebFile](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-WebFile.ps1) diff --git a/input/en-us/create/functions/get-webfilename.md b/input/en-us/create/functions/get-webfilename.md deleted file mode 100644 index 5d5e466c3d..0000000000 --- a/input/en-us/create/functions/get-webfilename.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -Order: 170 -xref: get-webfilename -Title: Get-WebFileName -Description: Information on Get-WebFileName function -RedirectFrom: - - docs/helpers-get-web-file-name - - docs/helpersgetwebfilename ---- - -# Get-WebFileName - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-WebFileName.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Gets the original file name from a url. Used by Get-WebFile to determine -the original file name for a file. - -## Syntax - -~~~powershell -Get-WebFileName ` - [-Url <String>] ` - -DefaultName <String> ` - [-UserAgent <String>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Uses several techniques to determine the original file name of the file -based on the url for the file. - -## Notes - -Falls back to DefaultName when the name cannot be determined. - -Chocolatey works best when the packages contain the software it is -managing and doesn't require downloads. However most software in the -Windows world requires redistribution rights and when sharing packages -publicly (like on the [community feed](https://community.chocolatey.org/packages)), maintainers may not have those -aforementioned rights. Chocolatey understands how to work with that, -hence this function. You are not subject to this limitation with -internal packages. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-WebFileName -Url $url -DefaultName $originalFileName - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Url [<String>] -This is the url to a file that will be possibly downloaded. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -DefaultName <String> -The name of the file to use when not able to determine the file name -from the url response. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -UserAgent [<String>] -The user agent to use as part of the request. Defaults to 'chocolatey -command line'. - -Property | Value ----------------------- | ----------------------- -Aliases | -Required? | false -Position? | named -Default Value | chocolatey command line -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Get-WebHeaders](xref:get-webheaders) - * [Get-ChocolateyWebFile](xref:get-chocolateywebfile) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-WebFileName -Full`. - -View the source for [Get-WebFileName](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-WebFileName.ps1) diff --git a/input/en-us/create/functions/get-webheaders.md b/input/en-us/create/functions/get-webheaders.md deleted file mode 100644 index a5aa3e4e79..0000000000 --- a/input/en-us/create/functions/get-webheaders.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -Order: 180 -xref: get-webheaders -Title: Get-WebHeaders -Description: Information on Get-WebHeaders function -RedirectFrom: - - docs/helpers-get-web-headers - - docs/helpersgetwebheaders ---- - -# Get-WebHeaders - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-WebHeaders.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Gets the request/response headers for a url. - -## Syntax - -~~~powershell -Get-WebHeaders ` - [-Url <String>] ` - [-UserAgent <String>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This is a low-level function that is used by Chocolatey to get the -headers for a request/response to better help when getting and -validating internet resources. - - -## Aliases - -None - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Url [<String>] -This is the url to get a request/response from. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -UserAgent [<String>] -The user agent to use as part of the request. Defaults to 'chocolatey -command line'. - -Property | Value ----------------------- | ----------------------- -Aliases | -Required? | false -Position? | 2 -Default Value | chocolatey command line -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Get-ChocolateyWebFile](xref:get-chocolateywebfile) - * [Get-WebFileName](xref:get-webfilename) - * [Get-WebFile](xref:get-webfile) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-WebHeaders -Full`. - -View the source for [Get-WebHeaders](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-WebHeaders.ps1) diff --git a/input/en-us/create/functions/index.md b/input/en-us/create/functions/index.md deleted file mode 100644 index b2e3012a61..0000000000 --- a/input/en-us/create/functions/index.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -Order: 40 -xref: powershell-reference -Title: PowerShell Functions Reference -Description: PowerShell Functions aka Helpers Reference -RedirectFrom: - - docs/helpers-reference - - docs/HelpersReference ---- - -# PowerShell Functions aka Helpers Reference - -<!-- This documentation file is automatically generated from the files at $sourceFunctions using $($sourceLocation)GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -## Summary - -In your Chocolatey packaging, you have the ability to use these functions (and others with Chocolatey's [PowerShell Extensions](xref:extensions)) to work with all aspects of software management. Keep in mind Chocolatey's automation scripts are just PowerShell, so you can do manage anything you want. - -> :choco-info: **NOTE** -> -> These scripts are for package scripts, not for use directly in PowerShell. This is in the create packages section, not the using Chocolatey section. - -## Main Functions - -These functions call other functions and many times may be the only thing you need in your [chocolateyInstall.ps1 file](xref:chocolatey-install-ps1). - -* [Install-ChocolateyPackage](xref:install-chocolateypackage) -* [Install-ChocolateyZipPackage](xref:install-chocolateyzippackage) -* [Install-ChocolateyPowershellCommand](xref:install-chocolateypowershellcommand) -* [Install-ChocolateyVsixPackage](xref:install-chocolateyvsixpackage) - -## More Functions - -### Administrative Access Functions - -When creating packages that need to run one of the following commands below, one should add the tag `admin` to the nuspec. - -* [Install-ChocolateyPackage](xref:install-chocolateypackage) -* [Start-ChocolateyProcessAsAdmin](xref:start-chocolateyprocessasadmin) -* [Install-ChocolateyInstallPackage](xref:install-chocolateyinstallpackage) -* [Install-ChocolateyPath](xref:install-chocolateypath) - when specifying machine path -* [Install-ChocolateyEnvironmentVariable](xref:install-chocolateyenvironmentvariable) - when specifying machine path -* [Install-ChocolateyExplorerMenuItem](xref:install-chocolateyexplorermenuitem) -* [Install-ChocolateyFileAssociation](xref:install-chocolateyfileassociation) -* [Uninstall-ChocolateyPath](xref:uninstall-chocolateypath) - when specifying machine path - -### Non-Administrator Safe Functions - -When you have a need to run Chocolatey without Administrative access required (non-default install location), you can run the following functions without administrative access. - -These are the functions from above as one list. - -* [Install-ChocolateyZipPackage](xref:install-chocolateyzippackage) -* [Install-ChocolateyPowershellCommand](xref:install-chocolateypowershellcommand) -* [Get-ChocolateyPath](xref:get-chocolateypath) -* [Get-ChocolateyWebFile](xref:get-chocolateywebfile) -* [Get-ChocolateyUnzip](xref:get-chocolateyunzip) -* [Install-ChocolateyPath](xref:install-chocolateypath) - when specifying user path -* [Install-ChocolateyEnvironmentVariable](xref:install-chocolateyenvironmentvariable) - when specifying user path -* [Install-ChocolateyPinnedTaskBarItem](xref:install-chocolateypinnedtaskbaritem) -* [Install-ChocolateyShortcut](xref:install-chocolateyshortcut) -* [Uninstall-ChocolateyPath](xref:uninstall-chocolateypath) - when specifying user path -* [Update-SessionEnvironment](xref:update-sessionenvironment) -* [Get-PackageParameters](xref:get-packageparameters) - -## Complete List (alphabetical order) - - * [Format-FileSize](xref:format-filesize) - * [Get-ChecksumValid](xref:get-checksumvalid) - * [Get-ChocolateyConfigValue](xref:get-chocolateyconfigvalue) - * [Get-ChocolateyPath](xref:get-chocolateypath) - * [Get-ChocolateyUnzip](xref:get-chocolateyunzip) - * [Get-ChocolateyWebFile](xref:get-chocolateywebfile) - * [Get-FtpFile](xref:get-ftpfile) - * [Get-OSArchitectureWidth](xref:get-osarchitecturewidth) - * [Get-PackageParameters](xref:get-packageparameters) - * [Get-ToolsLocation](xref:get-toolslocation) - * [Get-UACEnabled](xref:get-uacenabled) - * [Get-UninstallRegistryKey](xref:get-uninstallregistrykey) - * [Get-VirusCheckValid](xref:get-viruscheckvalid) - * [Get-WebFile](xref:get-webfile) - * [Get-WebFileName](xref:get-webfilename) - * [Get-WebHeaders](xref:get-webheaders) - * [Install-BinFile](xref:install-binfile) - * [Install-ChocolateyEnvironmentVariable](xref:install-chocolateyenvironmentvariable) - * [Install-ChocolateyExplorerMenuItem](xref:install-chocolateyexplorermenuitem) - * [Install-ChocolateyFileAssociation](xref:install-chocolateyfileassociation) - * [Install-ChocolateyInstallPackage](xref:install-chocolateyinstallpackage) - * [Install-ChocolateyPackage](xref:install-chocolateypackage) - * [Install-ChocolateyPinnedTaskBarItem](xref:install-chocolateypinnedtaskbaritem) - * [Install-ChocolateyPowershellCommand](xref:install-chocolateypowershellcommand) - * [Install-ChocolateyShortcut](xref:install-chocolateyshortcut) - * [Install-ChocolateyVsixPackage](xref:install-chocolateyvsixpackage) - * [Install-ChocolateyZipPackage](xref:install-chocolateyzippackage) - * [Install-Vsix](xref:install-vsix) - * [Set-PowerShellExitCode](xref:set-powershellexitcode) - * [Start-ChocolateyProcessAsAdmin](xref:start-chocolateyprocessasadmin) - * [Uninstall-BinFile](xref:uninstall-binfile) - * [Uninstall-ChocolateyEnvironmentVariable](xref:uninstall-chocolateyenvironmentvariable) - * [Uninstall-ChocolateyPackage](xref:uninstall-chocolateypackage) - * [Uninstall-ChocolateyPath](xref:uninstall-chocolateypath) - * [Uninstall-ChocolateyZipPackage](xref:uninstall-chocolateyzippackage) - * [Write-FunctionCallLogMessage](xref:write-functioncalllogmessage) - -## Chocolatey for Business Functions - - * [Install-ChocolateyWindowsService](xref:install-chocolateywindowsservice) - * [Start-ChocolateyWindowsService](xref:start-chocolateywindowsservice) - * [Stop-ChocolateyWindowsService](xref:stop-chocolateywindowsservice) - * [Uninstall-ChocolateyWindowsService](xref:uninstall-chocolateywindowsservice) - -## Variables - -There are also a number of environment variables providing access to some values from the nuspec and other information that may be useful. They are accessed via `$env:variableName`. - -### Environment Variables - -Chocolatey makes a number of environment variables available (You can access any of these with $env:TheVariableNameBelow): - - * TEMP/TMP - Overridden to the CacheLocation, but may be the same as the original TEMP folder. - * ChocolateyInstall - Top level folder where Chocolatey is installed. - * ChocolateyPackageName - The name of the package, equivalent to the lower case `<id />` field in the nuspec. - * ChocolateyPackageTitle - The title of the package, equivalent to the `<title />` field in the nuspec. - * ChocolateyPackageVersion - The version of the package. - * Prior to Chocolatey CLI version 2.1.0 this is equivalent to the `<version />` field in the nuspec. - * Starting with Chocolatey CLI version 2.1.0 this is equivalent to the [normalized version](xref:upgrading-to-chocolatey-v2-v6#package-version-normalization) of the `<version />` field in the nuspec. - * If you rely on `ChocolateyPackageVersion` in a URL, ensure that all possible permutations of the package version work (eg: `1.0.0.0`, `1.0.0`, `1.0`, `1.0.00.0`). - -#### Advanced Environment Variables - -The following are more advanced settings: - - * ChocolateyPackageParameters - Parameters to use with packaging, not the same as install arguments (which are passed directly to the native installer). Based on `--package-parameters`. - * CHOCOLATEY_VERSION - The version of Choco you normally see. Use if you are 'lighting' things up based on choco version, otherwise take a dependency on the specific version you need. - * ChocolateyForceX86 = If available and set to 'true', then user has requested 32bit version. Automatically handled in built in Choco functions. - * OS_PLATFORM - Like Windows, macOS, Linux. - * OS_VERSION - The version of OS, like 6.1 something something for Windows. - * OS_NAME - The reported name of the OS. - * IS_PROCESSELEVATED = Is the process elevated? - * ChocolateyPackageInstallLocation - Install location of the software that the package installs. Displayed at the end of the package install. - -#### Set By Options and Configuration - -Some environment variables are set based on options that are passed, configuration and/or features that are turned on: - - * ChocolateyExitOnRebootDetected - Are we exiting on a detected reboot? Set by `--exit-when-reboot-detected` or the feature `exitOnRebootDetected`. - * ChocolateyEnvironmentDebug - Was `--debug` passed? If using the built-in PowerShell host, this is always true (but only logs debug messages to console if `--debug` was passed). - * ChocolateyEnvironmentVerbose - Was `--verbose` passed? If using the built-in PowerShell host, this is always true (but only logs verbose messages to console if `--verbose` was passed). - * ChocolateyForce - Was `--force` passed? - * ChocolateyForceX86 - Was `-x86` passed? - * ChocolateyRequestTimeout - How long before a web request will time out. Set by config `webRequestTimeoutSeconds`. - * ChocolateyResponseTimeout - How long to wait for a download to complete? Set by config `commandExecutionTimeoutSeconds`. - * ChocolateyPowerShellHost - Are we using the built-in PowerShell host? Set by `--use-system-powershell` or the feature `powershellHost`. - -#### Business Edition Variables - - * ChocolateyInstallArgumentsSensitive - Encrypted arguments passed from command line `--install-arguments-sensitive` that are not logged anywhere. - * ChocolateyPackageParametersSensitive - Package parameters passed from command line `--package-parameters-sensitive` that are not logged anywhere. - * ChocolateyLicensedVersion - What version is the licensed edition on? - * ChocolateyLicenseType - What edition / type of the licensed edition is installed? - -#### Experimental Environment Variables - -The following are experimental or use not recommended: - - * OS_IS64BIT = This may not return correctly - it may depend on the process the app is running under. - * CHOCOLATEY_VERSION_PRODUCT = the version of Choco that may match CHOCOLATEY_VERSION but may be different - based on git describe. - * IS_ADMIN = Is the user an administrator? But doesn't tell you if the process is elevated. - -#### Not Useful Or Anti-Pattern If Used - - * ChocolateyInstallOverride - Not for use in package automation scripts. Based on `--override-arguments` being passed. - * ChocolateyInstallArguments - The installer arguments meant for the native installer. You should use chocolateyPackageParameters instead. Based on `--install-arguments` being passed. - * ChocolateyIgnoreChecksums - Was `--ignore-checksums` passed or the feature `checksumFiles` turned off? - * ChocolateyAllowEmptyChecksums - Was `--allow-empty-checksums` passed or the feature `allowEmptyChecksums` turned on? - * ChocolateyAllowEmptyChecksumsSecure - Was `--allow-empty-checksums-secure` passed or the feature `allowEmptyChecksumsSecure` turned on? - * ChocolateyChecksum32 - Was `--download-checksum` passed? - * ChocolateyChecksumType32 - Was `--download-checksum-type` passed? - * ChocolateyChecksum64 - Was `--download-checksum-x64` passed? - * ChocolateyChecksumType64 - Was `--download-checksum-type-x64` passed? - * ChocolateyPackageExitCode - The exit code of the script that just ran - usually set by `Set-PowerShellExitCode`. - * ChocolateyLastPathUpdate - Set by Chocolatey as part of install, but not used for anything in particular in packaging. - * ChocolateyProxyLocation - The explicit proxy location as set in the configuration `proxy`. - * ChocolateyDownloadCache - Use available download cache? Set by `--skip-download-cache`, `--use-download-cache`, or feature `downloadCache`. - * ChocolateyProxyBypassList - Explicitly set locations to ignore in configuration `proxyBypassList`. - * ChocolateyProxyBypassOnLocal - Should the proxy bypass on local connections? Set based on configuration `proxyBypassOnLocal`. - * http_proxy - Set by original `http_proxy` passthrough, or same as `ChocolateyProxyLocation` if explicitly set. - * https_proxy - Set by original `https_proxy` passthrough, or same as `ChocolateyProxyLocation` if explicitly set. - * no_proxy- Set by original `no_proxy` passthrough, or same as `ChocolateyProxyBypassList` if explicitly set. - * ChocolateyPackageFolder - Not for use in package automation scripts. Recommend using `$toolsDir = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)"` as per template generated by `choco new`. - * ChocolateyToolsLocation - Not for use in package automation scripts. Recommend using Get-ToolsLocation instead. diff --git a/input/en-us/create/functions/install-binfile.md b/input/en-us/create/functions/install-binfile.md deleted file mode 100644 index a10b9e669f..0000000000 --- a/input/en-us/create/functions/install-binfile.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -Order: 190 -xref: install-binfile -Title: Install-BinFile -Description: Information on Install-BinFile function -RedirectFrom: - - docs/helpers-install-bin-file - - docs/helpersinstallbinfile ---- - -# Install-BinFile - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-BinFile.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Creates a shim (or batch redirect) for a file that is on the PATH. - -## Syntax - -~~~powershell -Install-BinFile ` - -Name <String> ` - -Path <String> ` - [-UseStart] ` - [-Command <String>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Chocolatey installs have the folder `$($env:ChocolateyInstall)\bin` -included in the PATH environment variable. Chocolatey automatically -shims executables in package folders that are not explicitly ignored, -putting them into the bin folder (and subsequently onto the PATH). - -When you have other files you want to shim to add them to the PATH or -if you want to handle the shimming explicitly, use this function. - -If you do use this function, ensure you also add `Uninstall-BinFile` to -your `chocolateyUninstall.ps1` script as Chocolatey will not -automatically clean up shims created with this function. - -## Notes - -Not normally needed for exe files in the package folder, those are -automatically discovered and added as shims after the install script -completes. - -## Aliases - -`Add-BinFile` -`Generate-BinFile` - - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Name <String> -The name of the redirect file, will have .exe appended to it. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Path <String> -The path to the original file. Can be relative from -`$($env:ChocolateyInstall)\bin` back to your file or a full path to the -file. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -UseStart -This should be passed if the shim should not wait on the action to -complete. This is usually the case with GUI apps, you don't want the -command shell blocked waiting for the GUI app to be shut back down. - -Property | Value ----------------------- | ----- -Aliases | isGui -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -Command [<String>] -OPTIONAL - This is any additional command arguments you want passed -every time to the command. This is not normally used, but may be -necessary if you are calling something and then your application. For -example if you are calling Java with your JAR, the command would be the -JAR file plus any other options to start Java appropriately. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Uninstall-BinFile](xref:uninstall-binfile) - * [Install-ChocolateyShortcut](xref:install-chocolateyshortcut) - * [Install-ChocolateyPath](xref:install-chocolateypath) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Install-BinFile -Full`. - -View the source for [Install-BinFile](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-BinFile.ps1) diff --git a/input/en-us/create/functions/install-chocolateyenvironmentvariable.md b/input/en-us/create/functions/install-chocolateyenvironmentvariable.md deleted file mode 100644 index 3060d65212..0000000000 --- a/input/en-us/create/functions/install-chocolateyenvironmentvariable.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -Order: 200 -xref: install-chocolateyenvironmentvariable -Title: Install-ChocolateyEnvironmentVariable -Description: Information on Install-ChocolateyEnvironmentVariable function -RedirectFrom: - - docs/helpers-install-chocolatey-environment-variable - - docs/helpersinstallchocolateyenvironmentvariable ---- - -# Install-ChocolateyEnvironmentVariable - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyEnvironmentVariable.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -> :choco-info: **NOTE** -> -> Administrative Access Required when `-VariableType 'Machine'.` - -Creates a persistent environment variable. - -## Syntax - -~~~powershell -Install-ChocolateyEnvironmentVariable ` - [-VariableName <String>] ` - [-VariableValue <String>] ` - [-VariableType {Process | User | Machine}] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Install-ChocolateyEnvironmentVariable creates an environment variable -with the specified name and value. The variable is persistent and -will remain after reboots and across multiple PowerShell and command -line sessions. The variable can be scoped either to the User or to -the Machine. If Machine level scoping is specified, the command is -elevated to an administrative session. - -## Notes - -This command will assert UAC/Admin privileges on the machine when -`-VariableType Machine`. - -This will add the environment variable to the current session. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -# Creates a User environment variable "JAVA_HOME" pointing to -# "d:\oracle\jdk\bin". -Install-ChocolateyEnvironmentVariable "JAVA_HOME" "d:\oracle\jdk\bin" -~~~ - -**EXAMPLE 2** - -~~~powershell - -# Creates a User environment variable "_NT_SYMBOL_PATH" pointing to -# "symsrv*symsrv.dll*f:\localsymbols*http://msdl.microsoft.com/download/symbols". -# The command will be elevated to admin privileges. -Install-ChocolateyEnvironmentVariable ` - -VariableName "_NT_SYMBOL_PATH" ` - -VariableValue "symsrv*symsrv.dll*f:\localsymbols*http://msdl.microsoft.com/download/symbols" ` - -VariableType Machine -~~~ - -**EXAMPLE 3** - -~~~powershell - -# Remove an environment variable -Install-ChocolateyEnvironmentVariable -VariableName 'bob' -VariableValue $null -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -VariableName [<String>] -The name or key of the environment variable - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -VariableValue [<String>] -A string value assigned to the above name. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -VariableType -Specifies whether this variable is to be accessible at either the -individual user level or at the Machine level. - - -Valid options: Process, User, Machine - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | User -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Uninstall-ChocolateyEnvironmentVariable](xref:uninstall-chocolateyenvironmentvariable) - * [Get-EnvironmentVariable](xref:get-environmentvariable) - * [Set-EnvironmentVariable](xref:set-environmentvariable) - * [Install-ChocolateyPath](xref:install-chocolateypath) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Install-ChocolateyEnvironmentVariable -Full`. - -View the source for [Install-ChocolateyEnvironmentVariable](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyEnvironmentVariable.ps1) diff --git a/input/en-us/create/functions/install-chocolateyexplorermenuitem.md b/input/en-us/create/functions/install-chocolateyexplorermenuitem.md deleted file mode 100644 index 30b318239a..0000000000 --- a/input/en-us/create/functions/install-chocolateyexplorermenuitem.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -Order: 210 -xref: install-chocolateyexplorermenuitem -Title: Install-ChocolateyExplorerMenuItem -Description: Information on Install-ChocolateyExplorerMenuItem function -RedirectFrom: - - docs/helpers-install-chocolatey-explorer-menu-item - - docs/helpersinstallchocolateyexplorermenuitem ---- - -# Install-ChocolateyExplorerMenuItem - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyExplorerMenuItem.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -> :choco-info: **NOTE** -> -> Administrative Access Required. - -Creates a windows explorer context menu item that can be associated with -a command - -## Syntax - -~~~powershell -Install-ChocolateyExplorerMenuItem ` - -MenuKey <String> ` - [-MenuLabel <String>] ` - [-Command <String>] ` - [-Type <String>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Install-ChocolateyExplorerMenuItem can add an entry in the context menu -of Windows Explorer. The menu item is given a text label and a command. -The command can be any command accepted on the windows command line. The -menu item can be applied to either folder items or file items. - -Because this command accesses and edits the root class registry node, it -will be elevated to admin. - -## Notes - -This command will assert UAC/Admin privileges on the machine. - -Chocolatey will automatically add the path of the file or folder clicked -to the command. This is done simply by appending a %1 to the end of the -command. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -# This will create a context menu item in Windows Explorer when any file -# is right clicked. The menu item will appear with the text "Open with -# Sublime Text 2" and will invoke sublime text 2 when selected. -$sublimeDir = (Get-ChildItem $env:ALLUSERSPROFILE\chocolatey\lib\sublimetext* | select $_.last) -$sublimeExe = "$sublimeDir\tools\sublime_text.exe" -Install-ChocolateyExplorerMenuItem "sublime" "Open with Sublime Text 2" $sublimeExe -~~~ - -**EXAMPLE 2** - -~~~powershell - -# This will create a context menu item in Windows Explorer when any -# folder is right clicked. The menu item will appear with the text -# "Open with Sublime Text 2" and will invoke sublime text 2 when selected. -$sublimeDir = (Get-ChildItem $env:ALLUSERSPROFILE\chocolatey\lib\sublimetext* | select $_.last) -$sublimeExe = "$sublimeDir\tools\sublime_text.exe" -Install-ChocolateyExplorerMenuItem "sublime" "Open with Sublime Text 2" $sublimeExe "directory" -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -MenuKey <String> -A unique string to identify this menu item in the registry - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -MenuLabel [<String>] -The string that will be displayed in the context menu - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -Command [<String>] -A command line command that will be invoked when the menu item is -selected - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### -Type [<String>] -Specifies if the menu item should be applied to a folder or a file - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 4 -Default Value | file -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyShortcut](xref:install-chocolateyshortcut) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Install-ChocolateyExplorerMenuItem -Full`. - -View the source for [Install-ChocolateyExplorerMenuItem](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyExplorerMenuItem.ps1) diff --git a/input/en-us/create/functions/install-chocolateyfileassociation.md b/input/en-us/create/functions/install-chocolateyfileassociation.md deleted file mode 100644 index d3e9b69dac..0000000000 --- a/input/en-us/create/functions/install-chocolateyfileassociation.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -Order: 220 -xref: install-chocolateyfileassociation -Title: Install-ChocolateyFileAssociation -Description: Information on Install-ChocolateyFileAssociation function -RedirectFrom: - - docs/helpers-install-chocolatey-file-association - - docs/helpersinstallchocolateyfileassociation ---- - -# Install-ChocolateyFileAssociation - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyFileAssociation.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -> :choco-info: **NOTE** -> -> Administrative Access Required. - -Creates an association between a file extension and a executable. - -## Syntax - -~~~powershell -Install-ChocolateyFileAssociation ` - -Extension <String> ` - -Executable <String> ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Install-ChocolateyFileAssociation can associate a file extension -with a downloaded application. Once this command has created an -association, all invocations of files with the specified extension -will be opened via the executable specified. - -## Notes - -This command will assert UAC/Admin privileges on the machine. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -# This will create an association between Sublime Text 2 and all .txt -# files. Any .txt file opened will by default open with Sublime Text 2. -$sublimeDir = (Get-ChildItem $env:ALLUSERSPROFILE\chocolatey\lib\sublimetext* | select $_.last) -$sublimeExe = "$sublimeDir\tools\sublime_text.exe" -Install-ChocolateyFileAssociation ".txt" $sublimeExe -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Extension <String> -The file extension to be associated. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Executable <String> -The path to the application's executable to be associated. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Install-ChocolateyFileAssociation -Full`. - -View the source for [Install-ChocolateyFileAssociation](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyFileAssociation.ps1) diff --git a/input/en-us/create/functions/install-chocolateyinstallpackage.md b/input/en-us/create/functions/install-chocolateyinstallpackage.md deleted file mode 100644 index 8d88a13ea1..0000000000 --- a/input/en-us/create/functions/install-chocolateyinstallpackage.md +++ /dev/null @@ -1,323 +0,0 @@ ---- -Order: 230 -xref: install-chocolateyinstallpackage -Title: Install-ChocolateyInstallPackage -Description: Information on Install-ChocolateyInstallPackage function -RedirectFrom: - - docs/helpers-install-chocolatey-install-package - - docs/helpersinstallchocolateyinstallpackage ---- - -# Install-ChocolateyInstallPackage - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyInstallPackage.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -> :choco-info: **NOTE** -> -> Administrative Access Required. - -Installs software into "Programs and Features". Use -Install-ChocolateyPackage when software must be downloaded first. - -## Syntax - -~~~powershell -Install-ChocolateyInstallPackage ` - -PackageName <String> ` - [-FileType <String>] ` - [-SilentArgs <String[]>] ` - [-File <String>] ` - [-File64 <String>] ` - [-ValidExitCodes <Object>] ` - [-UseOnlyPackageSilentArguments] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This will run an installer (local file) on your machine. - -## Notes - -This command will assert UAC/Admin privileges on the machine. - -If you are embedding files into a package, ensure that you have the -rights to redistribute those files if you are sharing this package -publicly (like on the [community feed](https://community.chocolatey.org/packages)). Otherwise, please use -Install-ChocolateyPackage to download those resources from their -official distribution points. - -This is a native installer wrapper function. A "true" package will -contain all the run time files and not an installer. That could come -pre-zipped and require unzipping in a PowerShell script. Chocolatey -works best when the packages contain the software it is managing. Most -software in the Windows world comes as installers and Chocolatey -understands how to work with that, hence this wrapper function. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -$packageName= 'bob' -$toolsDir = "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)" -$fileLocation = Join-Path $toolsDir 'INSTALLER_EMBEDDED_IN_PACKAGE' - -$packageArgs = @{ - packageName = $packageName - fileType = 'msi' - file = $fileLocation - silentArgs = "/qn /norestart" - validExitCodes= @(0, 3010, 1641) - softwareName = 'Bob*' -} - -Install-ChocolateyInstallPackage @packageArgs -~~~ - -**EXAMPLE 2** - -~~~powershell - -$packageArgs = @{ - packageName = 'bob' - fileType = 'exe' - file = '\\SHARE_LOCATION\to\INSTALLER_FILE' - silentArgs = "/S" - validExitCodes= @(0) - softwareName = 'Bob*' -} - -Install-ChocolateyInstallPackage @packageArgs -~~~ - -**EXAMPLE 3** - -~~~powershell - -$packageName= 'bob' -$toolsDir = "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)" -$fileLocation = Join-Path $toolsDir 'someinstaller.msi' - -$packageArgs = @{ - packageName = $packageName - fileType = 'msi' - file = $fileLocation - silentArgs = "/qn /norestart MSIPROPERTY=`"true`"" - validExitCodes= @(0, 3010, 1641) - softwareName = 'Bob*' -} - -Install-ChocolateyInstallPackage @packageArgs -~~~ - -**EXAMPLE 4** - -~~~powershell - -$packageName= 'bob' -$toolsDir = "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)" -$fileLocation = Join-Path $toolsDir 'someinstaller.msi' -$mstFileLocation = Join-Path $toolsDir 'transform.mst' - -$packageArgs = @{ - packageName = $packageName - fileType = 'msi' - file = $fileLocation - silentArgs = "/qn /norestart TRANSFORMS=`"$mstFileLocation`"" - validExitCodes= @(0, 3010, 1641) - softwareName = 'Bob*' -} - -Install-ChocolateyInstallPackage @packageArgs -~~~ - -**EXAMPLE 5** - -~~~powershell -Install-ChocolateyInstallPackage 'bob' 'exe' '/S' "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)\bob.exe" - -~~~ - -**EXAMPLE 6** - -~~~powershell - -Install-ChocolateyInstallPackage -PackageName 'bob' -FileType 'exe' ` - -SilentArgs '/S' ` - -File "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)\bob.exe" ` - -ValidExitCodes @(0) -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -PackageName <String> -The name of the package - while this is an arbitrary value, it's -recommended that it matches the package id. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -FileType [<String>] -This is the extension of the file. This can be 'exe', 'msi', or 'msu'. -[Licensed editions](https://chocolatey.org/compare) of Chocolatey use this to automatically determine -silent arguments. If this is not provided, Chocolatey will -automatically determine this using the downloaded file's extension. - -Property | Value ----------------------- | -------------------------- -Aliases | installerType, installType -Required? | false -Position? | 2 -Default Value | exe -Accept Pipeline Input? | false - -### -SilentArgs [<String[]>] -OPTIONAL - These are the parameters to pass to the native installer, -including any arguments to make the installer silent/unattended. -Pro/Business Editions of Chocolatey will automatically determine the -installer type and merge the arguments with what is provided here. - -Try any of the to get the silent installer - -`/s /S /q /Q /quiet /silent /SILENT /VERYSILENT`. With msi it is always -`/quiet`. Please pass it in still but it will be overridden by -Chocolatey to `/quiet`. If you don't pass anything it could invoke the -installer with out any arguments. That means a nonsilent installer. - -Please include the `notSilent` tag in your Chocolatey package if you -are not setting up a silent/unattended package. Please note that if you -are submitting to the [community repository](https://community.chocolatey.org/packages), it is nearly a requirement -for the package to be completely unattended. - -When you are using this with an MSI, it will set up the arguments as -follows: `"C:\Full\Path\To\msiexec.exe" /i "$fileFullPath" $silentArgs`, -where `$fileFullPath` is `$file` or `$file64`, depending on what has been -decided to be used. - -When you use this with MSU, it is similar to MSI above in that it finds -the right executable to run. - -When you use this with executable installers, the `$fileFullPath` will -be `$file` (or `$file64`) and expects to be a full path to the file. If -the file is in the package, see the parameters for "File" and "File64" -to determine how you can get that path at runtime in a deterministic -way. SilentArgs is everything you call against that file, as in -`"$fileFullPath" $silentArgs"`. An example would be -`"c:\path\setup.exe" /S`, where `$fileFullPath = "c:\path\setup.exe"` -and `$silentArgs = "/S"`. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### -File [<String>] -Full file path to native installer to run. If embedding in the package, -you can get it to the path with -`"$(Split-Path -parent $MyInvocation.MyCommand.Definition)\\INSTALLER_FILE"` - -`FileFullPath` is an alias for File. - -This can be a 32-bit or 64-bit file. This is mandatory in earlier versions -of Chocolatey, but optional if File64 has been provided. - -Property | Value ----------------------- | ------------ -Aliases | fileFullPath -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### -File64 [<String>] -Full file path to a 64-bit native installer to run. -If embedding in the package, you can get it to the path with -`"$(Split-Path -parent $MyInvocation.MyCommand.Definition)\\INSTALLER_FILE"` - -Provide this when you want to provide both 32-bit and 64-bit -installers or explicitly only a 64-bit installer (which will cause a package -install failure on 32-bit systems). - -Property | Value ----------------------- | -------------- -Aliases | fileFullPath64 -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ValidExitCodes [<Object>] -Array of exit codes indicating success. Defaults to `@(0)`. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | @(0) -Accept Pipeline Input? | false - -### -UseOnlyPackageSilentArguments -Do not allow choco to provide/merge additional silent arguments and -only use the ones available with the package. - -Property | Value ----------------------- | ------------------------ -Aliases | useOnlyPackageSilentArgs -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyPackage](xref:install-chocolateypackage) - * [Uninstall-ChocolateyPackage](xref:uninstall-chocolateypackage) - * [Get-UninstallRegistryKey](xref:get-uninstallregistrykey) - * [Start-ChocolateyProcessAsAdmin](xref:start-chocolateyprocessasadmin) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Install-ChocolateyInstallPackage -Full`. - -View the source for [Install-ChocolateyInstallPackage](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyInstallPackage.ps1) diff --git a/input/en-us/create/functions/install-chocolateypackage.md b/input/en-us/create/functions/install-chocolateypackage.md deleted file mode 100644 index 6c981f7683..0000000000 --- a/input/en-us/create/functions/install-chocolateypackage.md +++ /dev/null @@ -1,550 +0,0 @@ ---- -Order: 240 -xref: install-chocolateypackage -Title: Install-ChocolateyPackage -Description: Information on Install-ChocolateyPackage function -RedirectFrom: - - docs/helpers-install-chocolatey-package - - docs/helpersinstallchocolateypackage ---- - -# Install-ChocolateyPackage - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyPackage.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -> :choco-info: **NOTE** -> -> Administrative Access Required. - -Installs software into "Programs and Features" based on a remote file -download. Use Install-ChocolateyInstallPackage when local or embedded -file. - -Building packages for an organization or for use internally? You want to -use Install-ChocolateyINSTALLPackage instead of this method (see links -below). - -## Syntax - -~~~powershell -Install-ChocolateyPackage ` - -PackageName <String> ` - [-FileType <String>] ` - [-SilentArgs <String[]>] ` - [-Url <String>] ` - [-Url64bit <String>] ` - [-ValidExitCodes <Object>] ` - [-Checksum <String>] ` - [-ChecksumType <String>] ` - [-Checksum64 <String>] ` - [-ChecksumType64 <String>] ` - [-Options <Hashtable>] ` - [-File <String>] ` - [-File64 <String>] ` - [-UseOnlyPackageSilentArguments] ` - [-UseOriginalLocation] ` - [-BeforeInstall <ScriptBlock>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This will download a native installer from a url and install it on your -machine. Has error handling built in. - -If you are embedding the file(s) directly in the package (or do not need -to download a file first), use Install-ChocolateyInstallPackage instead. - -Building packages for an organization or for use internally? You want to -use Install-ChocolateyINSTALLPackage instead of this method -(see links below). - -## Notes - -This command will assert UAC/Admin privileges on the machine. - -This is a native installer wrapper function. A "true" package will -contain all the run time files and not an installer. That could come -pre-zipped and require unzipping in a PowerShell script. Chocolatey -works best when the packages contain the software it is managing. Most -software in the Windows world comes as installers and Chocolatey -understands how to work with that, hence this wrapper function. - -Chocolatey works best when the packages contain the software it is -managing and doesn't require downloads. However most software in the -Windows world requires redistribution rights and when sharing packages -publicly (like on the [community feed](https://community.chocolatey.org/packages)), maintainers may not have those -aforementioned rights. Chocolatey understands how to work with that, -hence this function. You are not subject to this limitation with -internal packages. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -$packageName= 'bob' -$toolsDir = "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)" -$url = 'https://somewhere.com/file.msi' -$url64 = 'https://somewhere.com/file-x64.msi' - -$packageArgs = @{ - packageName = $packageName - fileType = 'msi' - url = $url - url64bit = $url64 - silentArgs = "/qn /norestart" - validExitCodes= @(0, 3010, 1641) - softwareName = 'Bob*' - checksum = '12345' - checksumType = 'sha256' - checksum64 = '123356' - checksumType64= 'sha256' -} - -Install-ChocolateyPackage @packageArgs -~~~ - -**EXAMPLE 2** - -~~~powershell - -$packageName= 'bob' -$toolsDir = "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)" -$url = 'https://somewhere.com/file.msi' -$url64 = 'https://somewhere.com/file-x64.msi' - - -$packageArgs = @{ - packageName = $packageName - fileType = 'msi' - url = $url - url64bit = $url64 - silentArgs = "/qn /norestart MSIPROPERTY=`"true`"" - validExitCodes= @(0, 3010, 1641) - softwareName = 'Bob*' - checksum = '12345' - checksumType = 'sha256' - checksum64 = '123356' - checksumType64= 'sha256' -} - -Install-ChocolateyPackage @packageArgs -~~~ - -**EXAMPLE 3** - -~~~powershell - -$packageName= 'bob' -$toolsDir = "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)" -$urlTransform = 'https://somewhere.com/file.mst' -$mstFileLocation = Join-Path $toolsDir 'transform.mst' - -Get-ChocolateyWebFile -PackageName 'bob' ` - -Url $urlTransform -FileFullPath $mstFileLocation ` - -Checksum '1234' -ChecksumType 'sha256' - -$packageArgs = @{ - packageName = $packageName - fileType = 'msi' - file = $fileLocation - silentArgs = "/qn /norestart TRANSFORMS=`"$mstFileLocation`"" - validExitCodes= @(0, 3010, 1641) - softwareName = 'Bob*' -} - -Install-ChocolateyInstallPackage @packageArgs -~~~ - -**EXAMPLE 4** - -~~~powershell - -Install-ChocolateyPackage 'StExBar' 'msi' '/quiet' ` - 'http://stexbar.googlecode.com/files/StExBar-1.8.3.msi' ` - 'http://stexbar.googlecode.com/files/StExBar64-1.8.3.msi' -~~~ - -**EXAMPLE 5** - -~~~powershell - -Install-ChocolateyPackage 'mono' 'exe' '/SILENT' ` - 'http://somewhere/something.exe' -ValidExitCodes @(0,21) -~~~ - -**EXAMPLE 6** - -~~~powershell - -Install-ChocolateyPackage 'ruby.devkit' 'exe' '/SILENT' ` - 'http://cdn.rubyinstaller.org/archives/devkits/DevKit-mingw64-32-4.7.2-20130224-1151-sfx.exe' ` - 'http://cdn.rubyinstaller.org/archives/devkits/DevKit-mingw64-64-4.7.2-20130224-1432-sfx.exe' ` - -checksum '9383f12958aafc425923e322460a84de' -checksumType 'md5' ` - -checksum64 'ce99d873c1acc8bffc639bd4e764b849' -~~~ - -**EXAMPLE 7** - -~~~powershell -Install-ChocolateyPackage 'bob' 'exe' '/S' 'https://somewhere/bob.exe' 'https://somewhere/bob-x64.exe' - -~~~ - -**EXAMPLE 8** - -~~~powershell - -$options = -@{ - Headers = @{ - Accept = 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8'; - 'Accept-Charset' = 'ISO-8859-1,utf-8;q=0.7,*;q=0.3'; - 'Accept-Language' = 'en-GB,en-US;q=0.8,en;q=0.6'; - Cookie = 'requiredinfo=info'; - Referer = 'https://somelocation.com/'; - } -} - -Install-ChocolateyPackage -PackageName 'package' -FileType 'exe' -SilentArgs '/S' 'https://somelocation.com/thefile.exe' -Options $options -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -PackageName <String> -The name of the package - while this is an arbitrary value, it's -recommended that it matches the package id. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -FileType [<String>] -This is the extension of the file. This can be 'exe', 'msi', or 'msu'. -[Licensed editions](https://chocolatey.org/compare) of Chocolatey use this to automatically determine -silent arguments. If this is not provided, Chocolatey will -automatically determine this using the downloaded file's extension. - -Property | Value ----------------------- | -------------------------- -Aliases | installerType, installType -Required? | false -Position? | 2 -Default Value | exe -Accept Pipeline Input? | false - -### -SilentArgs [<String[]>] -OPTIONAL - These are the parameters to pass to the native installer, -including any arguments to make the installer silent/unattended. -[Licensed editions](https://chocolatey.org/compare) of Chocolatey will automatically determine the -installer type and merge the arguments with what is provided here. - -Try any of the to get the silent (unattended) installer - -`/s /S /q /Q /quiet /silent /SILENT /VERYSILENT`. With msi it is always -`/quiet`. Please pass it in still but it will be overridden by -Chocolatey to `/quiet`. If you don't pass anything it could invoke the -installer with out any arguments. That means a nonsilent installer. - -Please include the `notSilent` tag in your Chocolatey package if you -are not setting up a silent/unattended package. Please note that if you -are submitting to the [community repository](https://community.chocolatey.org/packages), it is nearly a requirement -for the package to be completely unattended. - -When you are using this with an MSI, it will set up the arguments as -follows: -`"C:\Full\Path\To\msiexec.exe" /i "$downloadedFileFullPath" $silentArgs`, -where `$downloadedfileFullPath` is `$url` or `$url64`, depending on what -has been decided to be used. - -When you use this with MSU, it is similar to MSI above in that it finds -the right executable to run. - -When you use this with executable installers, the -`$downloadedFileFullPath` will also be `$url`/`$url64` SilentArgs is -everything you call against that file, as in -`"$fileFullPath" $silentArgs"`. An example would be -`"c:\path\setup.exe" /S`, where -`$downloadedfileFullPath = "c:\path\setup.exe"` and `$silentArgs = "/S"`. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### -Url [<String>] -This is the 32 bit url to download the resource from. This resource can -be used on 64 bit systems when a package has both a Url and Url64bit -specified if a user passes `--forceX86`. If there is only a 64 bit url -available, please remove do not use the parameter (only use Url64bit). -Will fail on 32bit systems if missing or if a user attempts to force -a 32 bit installation on a 64 bit system. - -Prefer HTTPS when available. Can be HTTP, FTP, or File URIs. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### -Url64bit [<String>] -OPTIONAL - If there is a 64 bit resource available, use this -parameter. Chocolatey will automatically determine if the user is -running a 64 bit OS or not and adjust accordingly. Please note that -the 32 bit url will be used in the absence of this. This parameter -should only be used for 64 bit native software. If the original Url -contains both (which is quite rare), set this to '$url' Otherwise remove -this parameter. - -Prefer HTTPS when available. Can be HTTP, FTP, or File URIs. - -Property | Value ----------------------- | ----- -Aliases | url64 -Required? | false -Position? | 5 -Default Value | -Accept Pipeline Input? | false - -### -ValidExitCodes [<Object>] -Array of exit codes indicating success. Defaults to `@(0)`. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | @(0) -Accept Pipeline Input? | false - -### -Checksum [<String>] -The checksum hash value of the Url resource. This allows a checksum to -be validated for files that are not local. The checksum type is covered -by ChecksumType. - -> :choco-info: **NOTE** -> -> Checksums in packages are meant as a measure to validate the -originally intended file that was used in the creation of a package is -the same file that is received at a future date. Since this is used for -other steps in the process related to the [community repository](https://community.chocolatey.org/packages), it -ensures that the file a user receives is the same file a maintainer -and a moderator (if applicable), plus any moderation review has -intended for you to receive with this package. If you are looking at a -remote source that uses the same url for updates, you will need to -ensure the package also stays updated in line with those remote -resource updates. You should look into [automatic packaging](xref:automatic-packaging) -to help provide that functionality. - -> :choco-info: **NOTE** -> -> To determine checksums, you can get that from the original -site if provided. You can also use the [checksum tool available on -the community feed](https://community.chocolatey.org/packages/checksum) (`choco install checksum`) -and use it e.g. `checksum -t sha256 -f path\to\file`. Ensure you -provide checksums for all remote resources used. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ChecksumType [<String>] -The type of checksum that the file is validated with - valid -values are 'md5', 'sha1', 'sha256' or 'sha512' - defaults to 'md5'. - -MD5 is not recommended as certain organizations need to use FIPS -compliant algorithms for hashing - see -https://support.microsoft.com/en-us/kb/811833 for more details. - -The recommendation is to use at least SHA256. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Checksum64 [<String>] -OPTIONAL if no Url64bit - The checksum hash value of the Url64bit -resource. This allows a checksum to be validated for files that are not -local. The checksum type is covered by ChecksumType64. - -> :choco-info: **NOTE** -> -> Checksums in packages are meant as a measure to validate the -originally intended file that was used in the creation of a package is -the same file that is received at a future date. Since this is used for -other steps in the process related to the [community repository](https://community.chocolatey.org/packages), it -ensures that the file a user receives is the same file a maintainer -and a moderator (if applicable), plus any moderation review has -intended for you to receive with this package. If you are looking at a -remote source that uses the same url for updates, you will need to -ensure the package also stays updated in line with those remote -resource updates. You should look into [automatic packaging](xref:automatic-packaging) -to help provide that functionality. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ChecksumType64 [<String>] -OPTIONAL - The type of checksum that the file is validated with - valid -values are 'md5', 'sha1', 'sha256' or 'sha512' - defaults to -ChecksumType parameter value. - -MD5 is not recommended as certain organizations need to use FIPS -compliant algorithms for hashing - see -https://support.microsoft.com/en-us/kb/811833 for more details. - -The recommendation is to use at least SHA256. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Options [<Hashtable>] -OPTIONAL - Specify custom headers. - -Property | Value ----------------------- | ----------------- -Aliases | -Required? | false -Position? | named -Default Value | @{Headers = @{} } -Accept Pipeline Input? | false - -### -File [<String>] -Will be used for Url if Url is empty. - -This parameter provides compatibility, but should not be used directly -and not with the community package repository until January 2018. - -Property | Value ----------------------- | ------------ -Aliases | fileFullPath -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -File64 [<String>] -Will be used for Url64bit if Url64bit is empty. - -This parameter provides compatibility, but should not be used directly -and not with the community package repository until January 2018. - -Property | Value ----------------------- | -------------- -Aliases | fileFullPath64 -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -UseOnlyPackageSilentArguments -Do not allow choco to provide/merge additional silent arguments and only -use the ones available with the package. - -Property | Value ----------------------- | ------------------------ -Aliases | useOnlyPackageSilentArgs -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -UseOriginalLocation -Do not download the resources. This is typically passed if Url/Url64bit -are pointed to local files or files on a share and those files should -be used in place. - -> :choco-info: **NOTE** -> -> You can also use `Install-ChocolateyInstallPackage` for the same -functionality (see links). - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -BeforeInstall [<ScriptBlock>] -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Get-ChocolateyWebFile](xref:get-chocolateywebfile) - * [Install-ChocolateyInstallPackage](xref:install-chocolateyinstallpackage) - * [Get-UninstallRegistryKey](xref:get-uninstallregistrykey) - * [Install-ChocolateyZipPackage](xref:install-chocolateyzippackage) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Install-ChocolateyPackage -Full`. - -View the source for [Install-ChocolateyPackage](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyPackage.ps1) diff --git a/input/en-us/create/functions/install-chocolateypinnedtaskbaritem.md b/input/en-us/create/functions/install-chocolateypinnedtaskbaritem.md deleted file mode 100644 index 326afe1a87..0000000000 --- a/input/en-us/create/functions/install-chocolateypinnedtaskbaritem.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -Order: 260 -xref: install-chocolateypinnedtaskbaritem -Title: Install-ChocolateyPinnedTaskBarItem -Description: Information on Install-ChocolateyPinnedTaskBarItem function -RedirectFrom: - - docs/helpers-install-chocolatey-pinned-task-bar-item - - docs/helpersinstallchocolateypinnedtaskbaritem ---- - -# Install-ChocolateyPinnedTaskBarItem - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyPinnedTaskBarItem.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Creates an item in the task bar linking to the provided path. - -## Syntax - -~~~powershell -Install-ChocolateyPinnedTaskBarItem ` - -TargetFilePath <String> ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - - -## Notes - -Does not work with SYSTEM, but does not error. It warns with the error -message. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -# This will create a Visual Studio task bar icon. -Install-ChocolateyPinnedTaskBarItem -TargetFilePath "${env:ProgramFiles(x86)}\Microsoft Visual Studio 11.0\Common7\IDE\devenv.exe" -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -TargetFilePath <String> -The path to the application that should be launched when clicking on the -task bar icon. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyShortcut](xref:install-chocolateyshortcut) - * [Install-ChocolateyExplorerMenuItem](xref:install-chocolateyexplorermenuitem) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Install-ChocolateyPinnedTaskBarItem -Full`. - -View the source for [Install-ChocolateyPinnedTaskBarItem](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyPinnedTaskBarItem.ps1) diff --git a/input/en-us/create/functions/install-chocolateypowershellcommand.md b/input/en-us/create/functions/install-chocolateypowershellcommand.md deleted file mode 100644 index a6e653ad67..0000000000 --- a/input/en-us/create/functions/install-chocolateypowershellcommand.md +++ /dev/null @@ -1,304 +0,0 @@ ---- -Order: 270 -xref: install-chocolateypowershellcommand -Title: Install-ChocolateyPowershellCommand -Description: Information on Install-ChocolateyPowershellCommand function -RedirectFrom: - - docs/helpers-install-chocolatey-powershell-command - - docs/helpersinstallchocolateypowershellcommand ---- - -# Install-ChocolateyPowershellCommand - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyPowershellCommand.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Installs a PowerShell Script as a command - -## Syntax - -~~~powershell -Install-ChocolateyPowershellCommand ` - [-PackageName <String>] ` - -PsFileFullPath <String> ` - [-Url <String>] ` - [-Url64bit <String>] ` - [-Checksum <String>] ` - [-ChecksumType <String>] ` - [-Checksum64 <String>] ` - [-ChecksumType64 <String>] ` - [-Options <Hashtable>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This will install a PowerShell script as a command on your system. Like -an executable can be run from a batch redirect, this will do the same, -calling PowerShell with this command and passing your arguments to it. -If you include a url, it will first download the PowerShell file. - -## Notes - -Chocolatey works best when the packages contain the software it is -managing and doesn't require downloads. However most software in the -Windows world requires redistribution rights and when sharing packages -publicly (like on the [community feed](https://community.chocolatey.org/packages)), maintainers may not have those -aforementioned rights. Chocolatey understands how to work with that, -hence this function. You are not subject to this limitation with -internal packages. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -$psFile = Join-Path $(Split-Path -Parent $MyInvocation.MyCommand.Definition) "Install-WindowsImage.ps1" -Install-ChocolateyPowershellCommand -PackageName 'installwindowsimage.powershell' -PSFileFullPath $psFile -~~~ - -**EXAMPLE 2** - -~~~powershell - -$psFile = Join-Path $(Split-Path -Parent $MyInvocation.MyCommand.Definition) ` - "Install-WindowsImage.ps1" -Install-ChocolateyPowershellCommand ` - -PackageName 'installwindowsimage.powershell' ` - -PSFileFullPath $psFile ` - -PSFileFullPath $psFile ` - -Url 'http://somewhere.com/downloads/Install-WindowsImage.ps1' -~~~ - -**EXAMPLE 3** - -~~~powershell - -$psFile = Join-Path $(Split-Path -Parent $MyInvocation.MyCommand.Definition) ` - "Install-WindowsImage.ps1" -Install-ChocolateyPowershellCommand ` - -PackageName 'installwindowsimage.powershell' ` - -PSFileFullPath $psFile ` - -Url 'http://somewhere.com/downloads/Install-WindowsImage.ps1' ` - -Url64 'http://somewhere.com/downloads/Install-WindowsImagex64.ps1' -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -PackageName [<String>] -The name of the package - while this is an arbitrary value, it's -recommended that it matches the package id. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -PsFileFullPath <String> -Full file path to PowerShell file to turn into a command. If embedding -it in the package next to the install script, the path will be like -`"$(Split-Path -parent $MyInvocation.MyCommand.Definition)\\Script.ps1"` - -`File` and `FileFullPath` are aliases for PsFileFullPath. - -Property | Value ----------------------- | ------------------ -Aliases | file, fileFullPath -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -Url [<String>] -This is the 32 bit url to download the resource from. This resource can -be used on 64 bit systems when a package has both a Url and Url64bit -specified if a user passes `--forceX86`. If there is only a 64 bit url -available, please remove do not use this parameter (only use Url64bit). -Will fail on 32bit systems if missing or if a user attempts to force -a 32 bit installation on a 64 bit system. - -Prefer HTTPS when available. Can be HTTP, FTP, or File URIs. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### -Url64bit [<String>] -OPTIONAL - If there is a 64 bit resource available, use this -parameter. Chocolatey will automatically determine if the user is -running a 64 bit OS or not and adjust accordingly. Please note that -the 32 bit url will be used in the absence of this. This parameter -should only be used for 64 bit native software. If the original Url -contains both (which is quite rare), set this to '$url' Otherwise remove -this parameter. - -Prefer HTTPS when available. Can be HTTP, FTP, or File URIs. - -Property | Value ----------------------- | ----- -Aliases | url64 -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### -Checksum [<String>] -The checksum hash value of the Url resource. This allows a checksum to -be validated for files that are not local. The checksum type is covered -by ChecksumType. - -> :choco-info: **NOTE** -> -> Checksums in packages are meant as a measure to validate the -originally intended file that was used in the creation of a package is -the same file that is received at a future date. Since this is used for -other steps in the process related to the [community repository](https://community.chocolatey.org/packages), it -ensures that the file a user receives is the same file a maintainer -and a moderator (if applicable), plus any moderation review has -intended for you to receive with this package. If you are looking at a -remote source that uses the same url for updates, you will need to -ensure the package also stays updated in line with those remote -resource updates. You should look into [automatic packaging](xref:automatic-packaging) -to help provide that functionality. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ChecksumType [<String>] -The type of checksum that the file is validated with - valid -values are 'md5', 'sha1', 'sha256' or 'sha512' - defaults to 'md5'. - -MD5 is not recommended as certain organizations need to use FIPS -compliant algorithms for hashing - see -https://support.microsoft.com/en-us/kb/811833 for more details. - -The recommendation is to use at least SHA256. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Checksum64 [<String>] -OPTIONAL if no Url64bit - The checksum hash value of the Url64bit -resource. This allows a checksum to be validated for files that are not -local. The checksum type is covered by ChecksumType64. - -> :choco-info: **NOTE** -> -> Checksums in packages are meant as a measure to validate the -originally intended file that was used in the creation of a package is -the same file that is received at a future date. Since this is used for -other steps in the process related to the [community repository](https://community.chocolatey.org/packages), it -ensures that the file a user receives is the same file a maintainer -and a moderator (if applicable), plus any moderation review has -intended for you to receive with this package. If you are looking at a -remote source that uses the same url for updates, you will need to -ensure the package also stays updated in line with those remote -resource updates. You should look into [automatic packaging](xref:automatic-packaging) -to help provide that functionality. - -> :choco-info: **NOTE** -> -> To determine checksums, you can get that from the original -site if provided. You can also use the [checksum tool available on -the community feed](https://community.chocolatey.org/packages/checksum) (`choco install checksum`) -and use it e.g. `checksum -t sha256 -f path\to\file`. Ensure you -provide checksums for all remote resources used. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ChecksumType64 [<String>] -OPTIONAL - The type of checksum that the file is validated with - valid -values are 'md5', 'sha1', 'sha256' or 'sha512' - defaults to -ChecksumType parameter value. - -MD5 is not recommended as certain organizations need to use FIPS -compliant algorithms for hashing - see -https://support.microsoft.com/en-us/kb/811833 for more details. - -The recommendation is to use at least SHA256. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Options [<Hashtable>] -OPTIONAL - Specify custom headers. - -Property | Value ----------------------- | ----------------- -Aliases | -Required? | false -Position? | named -Default Value | @{Headers = @{} } -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Get-ChocolateyWebFile](xref:get-chocolateywebfile) - * [Install-ChocolateyInstallPackage](xref:install-chocolateyinstallpackage) - * [Install-ChocolateyPackage](xref:install-chocolateypackage) - * [Install-ChocolateyZipPackage](xref:install-chocolateyzippackage) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Install-ChocolateyPowershellCommand -Full`. - -View the source for [Install-ChocolateyPowershellCommand](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyPowershellCommand.ps1) diff --git a/input/en-us/create/functions/install-chocolateyshortcut.md b/input/en-us/create/functions/install-chocolateyshortcut.md deleted file mode 100644 index 592da5961d..0000000000 --- a/input/en-us/create/functions/install-chocolateyshortcut.md +++ /dev/null @@ -1,240 +0,0 @@ ---- -Order: 280 -xref: install-chocolateyshortcut -Title: Install-ChocolateyShortcut -Description: Information on Install-ChocolateyShortcut function -RedirectFrom: - - docs/helpers-install-chocolatey-shortcut - - docs/helpersinstallchocolateyshortcut ---- - -# Install-ChocolateyShortcut - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyShortcut.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Creates a shortcut - -## Syntax - -~~~powershell -Install-ChocolateyShortcut ` - -ShortcutFilePath <String> ` - -TargetPath <String> ` - [-WorkingDirectory <String>] ` - [-Arguments <String>] ` - [-IconLocation <String>] ` - [-Description <String>] ` - [-WindowStyle <Int32>] ` - [-RunAsAdmin] ` - [-PinToTaskbar] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This adds a shortcut, at the specified location, with the option to specify -a number of additional properties for the shortcut, such as Working Directory, -Arguments, Icon Location, and Description. - -## Notes - -If this errors, as it may if being run under the local SYSTEM account with -particular folder that SYSTEM doesn't have, it will display a warning instead -of failing a package installation. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -# This will create a new shortcut at the location of "C:\test.lnk" and -# link to the file located at "C:\text.exe" - -Install-ChocolateyShortcut -ShortcutFilePath "C:\test.lnk" -TargetPath "C:\test.exe" -~~~ - -**EXAMPLE 2** - -~~~powershell - -# This will create a new shortcut at the location of "C:\notepad.lnk" -# and link to the Notepad application. In addition, other properties -# are being set to specify the working directory, an icon to be used for -# the shortcut, along with a description and arguments. - -Install-ChocolateyShortcut ` - -ShortcutFilePath "C:\notepad.lnk" ` - -TargetPath "C:\Windows\System32\notepad.exe" ` - -WorkingDirectory "C:\" ` - -Arguments "C:\test.txt" ` - -IconLocation "C:\test.ico" ` - -Description "This is the description" -~~~ - -**EXAMPLE 3** - -~~~powershell - -# Creates a new notepad shortcut on the root of c: that starts -# notepad.exe as Administrator. Shortcut is also pinned to taskbar. - -Install-ChocolateyShortcut ` - -ShortcutFilePath "C:\notepad.lnk" ` - -TargetPath "C:\Windows\System32\notepad.exe" ` - -WindowStyle 3 ` - -RunAsAdmin ` - -PinToTaskbar -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -ShortcutFilePath <String> -The full absolute path to where the shortcut should be created. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -TargetPath <String> -The full absolute path to the target for new shortcut. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -WorkingDirectory [<String>] -OPTIONAL - The full absolute path of the Working Directory that will be -used by the new shortcut. - -The directory will be created unless it contains environment -variable expansion like `%AppData%\FooBar`. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### -Arguments [<String>] -OPTIONAL - Additional arguments that should be passed along to the new -shortcut. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### -IconLocation [<String>] -OPTIONAL- The full absolute path to an icon file to be used for the new -shortcut. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 5 -Default Value | -Accept Pipeline Input? | false - -### -Description [<String>] -OPTIONAL - A text description to be associated with the new description. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 6 -Default Value | -Accept Pipeline Input? | false - -### -WindowStyle [<Int32>] -OPTIONAL - Type of windows target application should open with. -0 = Hidden, 1 = Normal Size, 3 = Maximized, 7 - Minimized. -Full list table 3.9 here: https://technet.microsoft.com/en-us/library/ee156605.aspx - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 7 -Default Value | 0 -Accept Pipeline Input? | false - -### -RunAsAdmin -OPTIONAL - Set "Run As Administrator" checkbox for the created the -shortcut. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -PinToTaskbar -OPTIONAL - Pin the new shortcut to the taskbar. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyExplorerMenuItem](xref:install-chocolateyexplorermenuitem) - * [Install-ChocolateyPinnedTaskBarItem](xref:install-chocolateypinnedtaskbaritem) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Install-ChocolateyShortcut -Full`. - -View the source for [Install-ChocolateyShortcut](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyShortcut.ps1) diff --git a/input/en-us/create/functions/install-chocolateyvsixpackage.md b/input/en-us/create/functions/install-chocolateyvsixpackage.md deleted file mode 100644 index 18b8cf95f8..0000000000 --- a/input/en-us/create/functions/install-chocolateyvsixpackage.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -Order: 290 -xref: install-chocolateyvsixpackage -Title: Install-ChocolateyVsixPackage -Description: Information on Install-ChocolateyVsixPackage function -RedirectFrom: - - docs/helpers-install-chocolatey-vsix-package - - docs/helpersinstallchocolateyvsixpackage ---- - -# Install-ChocolateyVsixPackage - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyVsixPackage.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Downloads and installs a VSIX package for Visual Studio - -## Syntax - -~~~powershell -Install-ChocolateyVsixPackage ` - -PackageName <String> ` - [-VsixUrl <String>] ` - [-VsVersion <Int32>] ` - [-Checksum <String>] ` - [-ChecksumType <String>] ` - [-Options <Hashtable>] ` - [-File <String>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -VSIX packages are Extensions for the Visual Studio IDE. The Visual -Studio Gallery at http://visualstudiogallery.msdn.microsoft.com/ is the -public extension feed and hosts thousands of extensions. You can locate -a VSIX Url by finding the download link of Visual Studio extensions on -the Visual Studio Gallery. - -## Notes - -Chocolatey works best when the packages contain the software it is -managing and doesn't require downloads. However most software in the -Windows world requires redistribution rights and when sharing packages -publicly (like on the [community feed](https://community.chocolatey.org/packages)), maintainers may not have those -aforementioned rights. Chocolatey understands how to work with that, -hence this function. You are not subject to this limitation with -internal packages. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -# This downloads the AutoWrockTestable VSIX from the Visual Studio -# Gallery and installs it to the latest version of VS. - -Install-ChocolateyVsixPackage -PackageName "MyPackage" ` - -VsixUrl http://visualstudiogallery.msdn.microsoft.com/ea3a37c9-1c76-4628-803e-b10a109e7943/file/73131/1/AutoWrockTestable.vsix -~~~ - -**EXAMPLE 2** - -~~~powershell - -# This downloads the AutoWrockTestable VSIX from the Visual Studio -# Gallery and installs it to Visual Studio 2012 (v11.0). - -Install-ChocolateyVsixPackage -PackageName "MyPackage" ` - -VsixUrl http://visualstudiogallery.msdn.microsoft.com/ea3a37c9-1c76-4628-803e-b10a109e7943/file/73131/1/AutoWrockTestable.vsix ` - -VsVersion 11 -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -PackageName <String> -The name of the package - while this is an arbitrary value, it's -recommended that it matches the package id. - -`Name` is an alias for PackageName. - -Property | Value ----------------------- | ----- -Aliases | name -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -VsixUrl [<String>] -The URL of the package to be installed. - -Prefer HTTPS when available. Can be HTTP, FTP, or File URIs. - -`Url` is an alias for VsixUrl. - -Property | Value ----------------------- | ----- -Aliases | url -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -VsVersion [<Int32>] -The major version number of Visual Studio where the -package should be installed. This is optional. If not -specified, the most recent Visual Studio installation -will be targeted. - -> :choco-info: **NOTE** -> -> For Visual Studio 2015, the VsVersion is 14. It can be determined -by looking at the folders under Program Files / Program Files (x86). - -`VisualStudioVersion` is an alias for VsVersion. - -Property | Value ----------------------- | ------------------- -Aliases | visualStudioVersion -Required? | false -Position? | 3 -Default Value | 0 -Accept Pipeline Input? | false - -### -Checksum [<String>] -The checksum hash value of the Url resource. This allows a checksum to -be validated for files that are not local. The checksum type is covered -by ChecksumType. - -> :choco-info: **NOTE** -> -> Checksums in packages are meant as a measure to validate the -originally intended file that was used in the creation of a package is -the same file that is received at a future date. Since this is used for -other steps in the process related to the [community repository](https://community.chocolatey.org/packages), it -ensures that the file a user receives is the same file a maintainer -and a moderator (if applicable), plus any moderation review has -intended for you to receive with this package. If you are looking at a -remote source that uses the same url for updates, you will need to -ensure the package also stays updated in line with those remote -resource updates. You should look into [automatic packaging](xref:automatic-packaging) -to help provide that functionality. - -> :choco-info: **NOTE** -> -> To determine checksums, you can get that from the original -site if provided. You can also use the [checksum tool available on -the community feed](https://community.chocolatey.org/packages/checksum) (`choco install checksum`) -and use it e.g. `checksum -t sha256 -f path\to\file`. Ensure you -provide checksums for all remote resources used. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ChecksumType [<String>] -The type of checksum that the file is validated with - valid -values are 'md5', 'sha1', 'sha256' or 'sha512' - defaults to 'md5'. - -MD5 is not recommended as certain organizations need to use FIPS -compliant algorithms for hashing - see -https://support.microsoft.com/en-us/kb/811833 for more details. - -The recommendation is to use at least SHA256. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Options [<Hashtable>] -OPTIONAL - Specify custom headers. - -Property | Value ----------------------- | ----------------- -Aliases | -Required? | false -Position? | named -Default Value | @{Headers = @{} } -Accept Pipeline Input? | false - -### -File [<String>] -Will be used for VsixUrl if VsixUrl is empty. - -This parameter provides compatibility, but should not be used directly -and not with the community package repository until January 2018. - -Property | Value ----------------------- | ------------ -Aliases | fileFullPath -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyPackage](xref:install-chocolateypackage) - * [Install-ChocolateyInstallPackage](xref:install-chocolateyinstallpackage) - * [Install-ChocolateyZipPackage](xref:install-chocolateyzippackage) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Install-ChocolateyVsixPackage -Full`. - -View the source for [Install-ChocolateyVsixPackage](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyVsixPackage.ps1) diff --git a/input/en-us/create/functions/install-chocolateywindowsservice.md b/input/en-us/create/functions/install-chocolateywindowsservice.md deleted file mode 100644 index d6f1db827b..0000000000 --- a/input/en-us/create/functions/install-chocolateywindowsservice.md +++ /dev/null @@ -1,270 +0,0 @@ ---- -Order: 285 -xref: install-chocolateywindowsservice -Title: Install-ChocolateyWindowsService -Description: Information on Install-ChocolateyWindowsService function -RedirectFrom: docs/helpers-install-chocolatey-windows-service ---- - -# Install-ChocolateyWindowsService - -> :choco-info: **NOTE** -> -> This function requires a Chocolatey for Business License to use. - -Installs a Windows Service using Install Util, plus some extra awesome-sauce. - -## Syntax - -~~~powershell -Install-ChocolateyWindowsService ` - -Name <string> ` - -ServiceExecutablePath <string> ` - [-Username <string>] ` - [-Password <string>] ` - [-DisplayName <string>] ` - [-Description <string>] ` - [-StartupType <ChocolateyWindowsServiceStartupType> {Unknown | Manual | Automatic | Disabled}] ` - [-DoNotStartService] ` - [-DoNotReinstallService] ` - [<CommonParameters>] -~~~ - -## Description -This installs a Windows Service onto a machine. When provided a user name, this -will ensure that user exists, is in the Administrators group, and has all of the -correct privileges to run as a service. For more details on the privileges, see -the Username parameter below. - -If a user is not a built in user and no password is provided, Chocolatey will -manage the password, which will be different for every machine and user and very -complex. For more details on the password, see the Password parameter below. - -One of the additional advanced features of this function is being able to -upgrade a service without shutting it down first - Chocolatey will move the -current running service and put in all of the new binaries. It will require a -restart of the service to move to the new code, but you can upgrade a service in -place without shutting it down first (one time). To use this, you must supply -the DoNotReinstallService switch. See the parameter below for more details. - -## Notes -Requires Chocolatey for Business. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Install-ChocolateyWindowsService -Name 'bob' -ServiceExecutablePath 'c:\somewhere\to\service.exe' -~~~ - -**EXAMPLE 2** - -~~~powershell -$toolsDir = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)" -$serviceExe = Join-Path $toolsDir 'service\dan-agent.exe' - -$packageArgs = @{ - Name = 'dan' - DisplayName = 'Dan Agent' - ServiceExecutablePath = $serviceExe - Username = 'DanTheBuilder' -} - -Install-ChocolateyWindowsService @packageArgs -~~~ - -**EXAMPLE 3** -This is the installation code for the Chocolatey Agent service itself. - -~~~powershell -$toolsDir = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)" -$serviceExe = Join-Path $toolsDir 'service\chocolatey-agent.exe' - -$packageArgs = @{ - Name = 'chocolatey-agent' - DisplayName = 'Chocolatey Agent' - Description = 'Chocolatey Agent is a backgound service for Chocolatey.' - StartupType = 'Automatic' - ServiceExecutablePath = $serviceExe - Username = 'ChocolateyLocalAdmin' -} - -$pp = Get-PackageParameters -if ($pp['Username']) { $packageArgs['Username'] = $pp['Username'] } -if ($pp['Password']) { $packageArgs['Password'] = $pp['Password'] } -if ($pp['EnterPassword']) { $packageArgs['Password'] = Read-Host "Enter password for $($packageArgs['Username']):" -AsSecureString} -if ($pp['UseDefaultChocolateyConfigUser']) { $packageArgs.Remove('Username') } - -# We don't want to shut down the service when we are running in background mode -if ($env:ChocolateyBackgroundService -eq 'true') { - Write-Warning "Detected running in background mode to upgrade the chocolatey-agent. Upgrade will attempt without restarting the service. \n Changes to service itself (like user/password) will be ignored." - $packageArgs['DoNotReinstallService'] = $true -} - -# Explicit request not to restart or reinstall the service. -if ($pp['NoRestartService'] -or $pp['DoNotReinstallService']) { - Write-Warning "Upgrade will attempt without restarting the service. \n Changes to service itself (like user/password) will be ignored." - $packageArgs['DoNotReinstallService'] = $true -} - -Install-ChocolateyWindowsService @packageArgs -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Description [<string>] -The description of the service. - - -Property | Value ----------------------- | --------------------- -Aliases | -Required? | false -Position? | Named -Default Value | -Accept Pipeline Input? | true (ByPropertyName) - -### -DisplayName [<string>] -The display name of the service. - - -Property | Value ----------------------- | --------------------- -Aliases | -Required? | false -Position? | Named -Default Value | -Accept Pipeline Input? | true (ByPropertyName) - -### -DoNotReinstallService -Do not uninstall/restart service. This is for advanced scenarios when you need -to deploy a newer version of a service and control when the restart happens over -to the newly deployed code. - - -Property | Value ----------------------- | --------------------- -Aliases | -Required? | false -Position? | Named -Default Value | -Accept Pipeline Input? | true (ByPropertyName) - -### -DoNotStartService -Do not start service after install. This keeps the service from starting up when -installing/upgrading. - - -Property | Value ----------------------- | --------------------- -Aliases | -Required? | false -Position? | Named -Default Value | -Accept Pipeline Input? | true (ByPropertyName) - -### -Name <string> -The name of the service to install. - - -Property | Value ----------------------- | --------------------- -Aliases | -Required? | true -Position? | 0 -Default Value | -Accept Pipeline Input? | true (ByPropertyName) - -### -Password [<string>] - -The password for the service - defaults to empty. If the user is not a built-in -account like LocalSystem and the user name is provided without a password being -provided, the password will automatically be a Chocolatey Managed Password. - -When Chocolatey manages the password for an account, it creates a very complex -password: - -* 32 characters long -* Uppercase, lowercase, numbers, and symbols to meet very stringent complexity - requirements -* Different for every machine -* Completely unguessable - -No one at Chocolatey Software could even tell you what the password is for a -particular machine without local access. - - -Property | Value ----------------------- | --------------------- -Aliases | -Required? | false -Position? | Named -Default Value | -Accept Pipeline Input? | true (ByPropertyName) - -### -ServiceExecutablePath <string> -The full path (absolute path) to the service executable file. - - -Property | Value ----------------------- | --------------------- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | true (ByPropertyName) - -### -StartupType [<ChocolateyWindowsServiceStartupType>] -The startup type of the service. Defaults to Automatic. - - -Property | Value ----------------------- | --------------------- -Aliases | -Required? | false -Position? | Named -Default Value | -Accept Pipeline Input? | true (ByPropertyName) - -### -Username [<string>] -The username for the service - defaults to LocalSystem (SYSTEM). If the user -does not exist, the user will be created. When a user is specified for a -service, the following things will also occur as part of this function: - -* User added to Administrators group -* User given privilege/right to run as a service (SeServiceLogonRight) -* User given privilege/right to log on as a batch (SeBatchLogonRight) -* User given privilege/right to log on interactively (SeInteractiveLogonRight) -* User given privilege/right to log on network (SeNetworkLogonRight) - - - -Property | Value ----------------------- | --------------------- -Aliases | user -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | true (ByPropertyName) - - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from licensed code. \ No newline at end of file diff --git a/input/en-us/create/functions/install-chocolateyzippackage.md b/input/en-us/create/functions/install-chocolateyzippackage.md deleted file mode 100644 index 696d21aee0..0000000000 --- a/input/en-us/create/functions/install-chocolateyzippackage.md +++ /dev/null @@ -1,353 +0,0 @@ ---- -Order: 300 -xref: install-chocolateyzippackage -Title: Install-ChocolateyZipPackage -Description: Information on Install-ChocolateyZipPackage function -RedirectFrom: - - docs/helpers-install-chocolatey-zip-package - - docs/helpersinstallchocolateyzippackage ---- - -# Install-ChocolateyZipPackage - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyZipPackage.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Downloads file from a url and unzips it on your machine. Use -Get-ChocolateyUnzip when local or embedded file. - -## Syntax - -~~~powershell -Install-ChocolateyZipPackage ` - -PackageName <String> ` - [-Url <String>] ` - -UnzipLocation <String> ` - [-Url64bit <String>] ` - [-SpecificFolder <String>] ` - [-Checksum <String>] ` - [-ChecksumType <String>] ` - [-Checksum64 <String>] ` - [-ChecksumType64 <String>] ` - [-Options <Hashtable>] ` - [-File <String>] ` - [-File64 <String>] ` - [-DisableLogging] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This will download a file from a url and unzip it on your machine. -If you are embedding the file(s) directly in the package (or do not need -to download a file first), use Get-ChocolateyUnzip instead. - -## Notes - -Chocolatey works best when the packages contain the software it is -managing and doesn't require downloads. However most software in the -Windows world requires redistribution rights and when sharing packages -publicly (like on the [community feed](https://community.chocolatey.org/packages)), maintainers may not have those -aforementioned rights. Chocolatey understands how to work with that, -hence this function. You are not subject to this limitation with -internal packages. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Install-ChocolateyZipPackage -PackageName 'gittfs' -Url 'https://github.com/downloads/spraints/git-tfs/GitTfs-0.11.0.zip' -UnzipLocation $gittfsPath - -~~~ - -**EXAMPLE 2** - -~~~powershell - -Install-ChocolateyZipPackage -PackageName 'sysinternals' ` - -Url 'http://download.sysinternals.com/Files/SysinternalsSuite.zip' ` - -UnzipLocation "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)" -~~~ - -**EXAMPLE 3** - -~~~powershell - -Install-ChocolateyZipPackage -PackageName 'sysinternals' ` - -Url 'http://download.sysinternals.com/Files/SysinternalsSuite.zip' ` - -UnzipLocation "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)" ` - -Url64 'http://download.sysinternals.com/Files/SysinternalsSuitex64.zip' -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -PackageName <String> -The name of the package - while this is an arbitrary value, it's -recommended that it matches the package id. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Url [<String>] -This is the 32 bit url to download the resource from. This resource can -be used on 64 bit systems when a package has both a Url and Url64bit -specified if a user passes `--forceX86`. If there is only a 64 bit url -available, please remove do not use the parameter (only use Url64bit). -Will fail on 32bit systems if missing or if a user attempts to force -a 32 bit installation on a 64 bit system. - -Prefer HTTPS when available. Can be HTTP, FTP, or File URIs. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -UnzipLocation <String> -This is the full path to a location to unzip the contents to, most -likely your script folder. If unzipping to your package folder, the path -will be like -`"$(Split-Path -Parent $MyInvocation.MyCommand.Definition)\\file.exe"` - -Property | Value ----------------------- | ----------- -Aliases | destination -Required? | true -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### -Url64bit [<String>] -OPTIONAL - If there is a 64 bit resource available, use this -parameter. Chocolatey will automatically determine if the user is -running a 64 bit OS or not and adjust accordingly. Please note that -the 32 bit url will be used in the absence of this. This parameter -should only be used for 64 bit native software. If the original Url -contains both (which is quite rare), set this to '$url' Otherwise remove -this parameter. - -Prefer HTTPS when available. Can be HTTP, FTP, or File URIs. - -Property | Value ----------------------- | ----- -Aliases | url64 -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### -SpecificFolder [<String>] -OPTIONAL - This is a specific directory within zip file to extract. The -folder and its contents will be extracted to the destination. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Checksum [<String>] -The checksum hash value of the Url resource. This allows a checksum to -be validated for files that are not local. The checksum type is covered -by ChecksumType. - -> :choco-info: **NOTE** -> -> Checksums in packages are meant as a measure to validate the -originally intended file that was used in the creation of a package is -the same file that is received at a future date. Since this is used for -other steps in the process related to the [community repository](https://community.chocolatey.org/packages), it -ensures that the file a user receives is the same file a maintainer -and a moderator (if applicable), plus any moderation review has -intended for you to receive with this package. If you are looking at a -remote source that uses the same url for updates, you will need to -ensure the package also stays updated in line with those remote -resource updates. You should look into [automatic packaging](xref:automatic-packaging) -to help provide that functionality. - -> :choco-info: **NOTE** -> -> To determine checksums, you can get that from the original -site if provided. You can also use the [checksum tool available on -the community feed](https://community.chocolatey.org/packages/checksum) (`choco install checksum`) -and use it e.g. `checksum -t sha256 -f path\to\file`. Ensure you -provide checksums for all remote resources used. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ChecksumType [<String>] -The type of checksum that the file is validated with - valid -values are 'md5', 'sha1', 'sha256' or 'sha512' - defaults to 'md5'. - -MD5 is not recommended as certain organizations need to use FIPS -compliant algorithms for hashing - see -https://support.microsoft.com/en-us/kb/811833 for more details. - -The recommendation is to use at least SHA256. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Checksum64 [<String>] -OPTIONAL if no Url64bit - The checksum hash value of the Url64bit -resource. This allows a checksum to be validated for files that are not -local. The checksum type is covered by ChecksumType64. - -> :choco-info: **NOTE** -> -> Checksums in packages are meant as a measure to validate the -originally intended file that was used in the creation of a package is -the same file that is received at a future date. Since this is used for -other steps in the process related to the [community repository](https://community.chocolatey.org/packages), it -ensures that the file a user receives is the same file a maintainer -and a moderator (if applicable), plus any moderation review has -intended for you to receive with this package. If you are looking at a -remote source that uses the same url for updates, you will need to -ensure the package also stays updated in line with those remote -resource updates. You should look into [automatic packaging](xref:automatic-packaging) -to help provide that functionality. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -ChecksumType64 [<String>] -OPTIONAL - The type of checksum that the file is validated with - valid -values are 'md5', 'sha1', 'sha256' or 'sha512' - defaults to -ChecksumType parameter value. - -MD5 is not recommended as certain organizations need to use FIPS -compliant algorithms for hashing - see -https://support.microsoft.com/en-us/kb/811833 for more details. - -The recommendation is to use at least SHA256. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -Options [<Hashtable>] -OPTIONAL - Specify custom headers. - -Property | Value ----------------------- | ----------------- -Aliases | -Required? | false -Position? | named -Default Value | @{Headers = @{} } -Accept Pipeline Input? | false - -### -File [<String>] -Will be used for Url if Url is empty. - -This parameter provides compatibility, but should not be used directly -and not with the community package repository until January 2018. - -Property | Value ----------------------- | ------------ -Aliases | fileFullPath -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -File64 [<String>] -Will be used for Url64bit if Url64bit is empty. - -This parameter provides compatibility, but should not be used directly -and not with the community package repository until January 2018. - -Property | Value ----------------------- | -------------- -Aliases | fileFullPath64 -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -DisableLogging -OPTIONAL - This disables logging of the extracted items. It speeds up -extraction of archives with many files. - -Usage of this parameter will prevent Uninstall-ChocolateyZipPackage -from working, extracted files will have to be cleaned up with -Remove-Item or a similar command instead. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Get-ChocolateyWebFile](xref:get-chocolateywebfile) - * [Get-ChocolateyUnzip](xref:get-chocolateyunzip) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Install-ChocolateyZipPackage -Full`. - -View the source for [Install-ChocolateyZipPackage](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyZipPackage.ps1) diff --git a/input/en-us/create/functions/install-vsix.md b/input/en-us/create/functions/install-vsix.md deleted file mode 100644 index f96e173e73..0000000000 --- a/input/en-us/create/functions/install-vsix.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -Order: 310 -xref: install-vsix -Title: Install-Vsix -Description: Information on Install-Vsix function -RedirectFrom: - - docs/helpers-install-vsix - - docs/helpersinstallvsix ---- - -# Install-Vsix - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-Vsix.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -DO NOT USE. Not part of the public API. - -## Syntax - -~~~powershell -Install-Vsix ` - -Installer <String> ` - -InstallFile <String> ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Installs a VSIX package into a particular version of Visual Studio. - -## Notes - -This is not part of the public API. Please use -Install-ChocolateyVsixPackage instead. - -## Aliases - -None - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Installer <String> -The path to the VSIX installer - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -InstallFile <String> -The VSIX file that is being installed. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyVsixPackage](xref:install-chocolateyvsixpackage) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Install-Vsix -Full`. - -View the source for [Install-Vsix](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-Vsix.ps1) diff --git a/input/en-us/create/functions/set-powershellexitcode.md b/input/en-us/create/functions/set-powershellexitcode.md deleted file mode 100644 index b92796b44e..0000000000 --- a/input/en-us/create/functions/set-powershellexitcode.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -Order: 330 -xref: set-powershellexitcode -Title: Set-PowerShellExitCode -Description: Information on Set-PowerShellExitCode function -RedirectFrom: - - docs/helpers-set-power-shell-exit-code - - docs/helperssetpowershellexitcode ---- - -# Set-PowerShellExitCode - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Set-PowerShellExitCode.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Sets the exit code for the PowerShell scripts. - -## Syntax - -~~~powershell -Set-PowerShellExitCode ` - [-ExitCode <Int32>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Sets the exit code as an environment variable that is checked and used -as the exit code for the package at the end of the package script. - -## Notes - -This tells PowerShell that it should prepare to shut down. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Set-PowerShellExitCode 3010 - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -ExitCode [<Int32>] -The exit code to set. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | 0 -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Set-PowerShellExitCode -Full`. - -View the source for [Set-PowerShellExitCode](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Set-PowerShellExitCode.ps1) diff --git a/input/en-us/create/functions/start-chocolateyprocessasadmin.md b/input/en-us/create/functions/start-chocolateyprocessasadmin.md deleted file mode 100644 index 5766fa903a..0000000000 --- a/input/en-us/create/functions/start-chocolateyprocessasadmin.md +++ /dev/null @@ -1,234 +0,0 @@ ---- -Order: 340 -xref: start-chocolateyprocessasadmin -Title: Start-ChocolateyProcessAsAdmin -Description: Information on Start-ChocolateyProcessAsAdmin function -RedirectFrom: - - docs/helpers-start-chocolatey-process-as-admin - - docs/helpersstartchocolateyprocessasadmin ---- - -# Start-ChocolateyProcessAsAdmin - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Start-ChocolateyProcessAsAdmin.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -> :choco-info: **NOTE** -> -> Administrative Access Required. - -Runs a process with administrative privileges. If `-ExeToRun` is not -specified, it is run with PowerShell. - -## Syntax - -~~~powershell -Start-ChocolateyProcessAsAdmin ` - [-Statements <String[]>] ` - [-ExeToRun <String>] ` - [-Elevated] ` - [-Minimized] ` - [-NoSleep] ` - [-ValidExitCodes <Object>] ` - [-WorkingDirectory <String>] ` - [-SensitiveStatements <String>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - - -## Notes - -This command will assert UAC/Admin privileges on the machine. - -Will automatically call Set-PowerShellExitCode to set the package exit -code in the following ways: - -- 4 if the binary turns out to be a text file. -- The same exit code returned from the process that is run. If a 3010 is returned, it will set 3010 for the package. - -Aliases `Start-ChocolateyProcess` and `Invoke-ChocolateyProcess`. - -## Aliases - -`Invoke-ChocolateyProcess` -`Start-ChocolateyProcess` - - -## Examples - - **EXAMPLE 1** - -~~~powershell -Start-ChocolateyProcessAsAdmin -Statements "$msiArgs" -ExeToRun 'msiexec' - -~~~ - -**EXAMPLE 2** - -~~~powershell -Start-ChocolateyProcessAsAdmin -Statements "$silentArgs" -ExeToRun $file - -~~~ - -**EXAMPLE 3** - -~~~powershell -Start-ChocolateyProcessAsAdmin -Statements "$silentArgs" -ExeToRun $file -ValidExitCodes @(0,21) - -~~~ - -**EXAMPLE 4** - -~~~powershell - -# Run PowerShell statements -$psFile = Join-Path "$(Split-Path -parent $MyInvocation.MyCommand.Definition)" 'someInstall.ps1' -Start-ChocolateyProcessAsAdmin "& `'$psFile`'" -~~~ - -**EXAMPLE 5** - -~~~powershell -# This also works for cmd and is required if you have any spaces in the paths within your command -$appPath = "$env:ProgramFiles\myapp" -$cmdBatch = "/c `"$appPath\bin\installmyappservice.bat`"" -Start-ChocolateyProcessAsAdmin $cmdBatch cmd -# or more explicitly -Start-ChocolateyProcessAsAdmin -Statements $cmdBatch -ExeToRun "cmd.exe" -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Statements [<String[]>] -Arguments to pass to `ExeToRun` or the PowerShell script block to be -run. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -ExeToRun [<String>] -The executable/application/installer to run. Defaults to `'powershell'`. - -Property | Value ----------------------- | ---------- -Aliases | -Required? | false -Position? | 2 -Default Value | powershell -Accept Pipeline Input? | false - -### -Elevated -Indicate whether the process should run elevated. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | True -Accept Pipeline Input? | false - -### -Minimized -Switch indicating if a Windows pops up (if not called with a silent -argument) that it should be minimized. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -NoSleep -Used only when calling PowerShell - indicates the window that is opened -should return instantly when it is complete. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -ValidExitCodes [<Object>] -Array of exit codes indicating success. Defaults to `@(0)`. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | @(0) -Accept Pipeline Input? | false - -### -WorkingDirectory [<String>] -The working directory for the running process. Defaults to -`Get-Location`. If current location is a UNC path, uses -`$env:TEMP` for default. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -SensitiveStatements [<String>] -Arguments to pass to `ExeToRun` that are not logged. - -Note that only [licensed versions](https://chocolatey.org/compare) of Chocolatey provide a way to pass -those values completely through without having them in the install -script or on the system in some way. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyPackage](xref:install-chocolateypackage) - * [Install-ChocolateyInstallPackage](xref:install-chocolateyinstallpackage) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Start-ChocolateyProcessAsAdmin -Full`. - -View the source for [Start-ChocolateyProcessAsAdmin](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Start-ChocolateyProcessAsAdmin.ps1) diff --git a/input/en-us/create/functions/start-chocolateywindowsservice.md b/input/en-us/create/functions/start-chocolateywindowsservice.md deleted file mode 100644 index 2599738647..0000000000 --- a/input/en-us/create/functions/start-chocolateywindowsservice.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -Order: 333 -xref: start-chocolateywindowsservice -Title: Start-ChocolateyWindowsService -Description: Information on Start-ChocolateyWindowsService function -RedirectFrom: docs/helpers-start-chocolatey-windows-service ---- - -# Start-ChocolateyWindowsService - -> :choco-info: **NOTE** -> -> This function requires a Chocolatey for Business License to use. - -Starts a Windows Service. - -## Syntax - -~~~powershell -Start-ChocolateyWindowsService ` - -Name <string> ` - [<CommonParameters>] -~~~ - - -## Aliases - -None - -## Notes -Requires Chocolatey for Business. - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Name <string> -The name of the service to start. Will throw an error if it doesn't exist. - - -Property | Value ----------------------- | --------------------- -Aliases | -Required? | true -Position? | 0 -Default Value | -Accept Pipeline Input? | true (ByPropertyName) - - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from licensed code. \ No newline at end of file diff --git a/input/en-us/create/functions/stop-chocolateywindowsservice.md b/input/en-us/create/functions/stop-chocolateywindowsservice.md deleted file mode 100644 index 95a2be7f74..0000000000 --- a/input/en-us/create/functions/stop-chocolateywindowsservice.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -Order: 336 -xref: stop-chocolateywindowsservice -Title: Stop-ChocolateyWindowsService -Description: Information on Stop-ChocolateyWindowsService function -RedirectFrom: docs/helpers-stop-chocolatey-windows-service ---- - -# Stop-ChocolateyWindowsService - -> :choco-info: **NOTE** -> -> This function requires a Chocolatey for Business License to use. - -Stops a Windows Service. - - -## Syntax - -~~~powershell -Stop-ChocolateyWindowsService ` - -Name <string> ` - [<CommonParameters>] -~~~ - - - -## Aliases - -None - -## Notes -Requires Chocolatey for Business. - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Name <string> -The name of the service to stop. Will not throw an error if it doesn't exist. - - -Property | Value ----------------------- | --------------------- -Aliases | -Required? | true -Position? | 0 -Default Value | -Accept Pipeline Input? | true (ByPropertyName) - - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from licensed code. \ No newline at end of file diff --git a/input/en-us/create/functions/uninstall-binfile.md b/input/en-us/create/functions/uninstall-binfile.md deleted file mode 100644 index 5866116b2b..0000000000 --- a/input/en-us/create/functions/uninstall-binfile.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -Order: 360 -xref: uninstall-binfile -Title: Uninstall-BinFile -Description: Information on Uninstall-BinFile function -RedirectFrom: - - docs/helpers-uninstall-bin-file - - docs/helpersuninstallbinfile ---- - -# Uninstall-BinFile - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Uninstall-BinFile.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Removes a shim (or batch redirect) for a file. - -## Syntax - -~~~powershell -Uninstall-BinFile ` - -Name <String> ` - [-Path <String>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Chocolatey installs have the folder `$($env:ChocolateyInstall)\bin` -included in the PATH environment variable. Chocolatey automatically -shims executables in package folders that are not explicitly ignored, -putting them into the bin folder (and subsequently onto the PATH). - -When you have other files you have shimmed, you need to use this -function to remove them from the bin folder. - -## Notes - -Not normally needed for exe files in the package folder, those are -automatically discovered and the shims removed. - -## Aliases - -`Remove-BinFile` - - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Name <String> -The name of the redirect file without ".exe" appended to it. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Path [<String>] -The path to the original file. Can be relative from -`$($env:ChocolateyInstall)\bin` back to your file or a full path to the -file. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-BinFile](xref:install-binfile) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Uninstall-BinFile -Full`. - -View the source for [Uninstall-BinFile](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Uninstall-BinFile.ps1) diff --git a/input/en-us/create/functions/uninstall-chocolateyenvironmentvariable.md b/input/en-us/create/functions/uninstall-chocolateyenvironmentvariable.md deleted file mode 100644 index c8720e9f64..0000000000 --- a/input/en-us/create/functions/uninstall-chocolateyenvironmentvariable.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -Order: 370 -xref: uninstall-chocolateyenvironmentvariable -Title: Uninstall-ChocolateyEnvironmentVariable -Description: Information on Uninstall-ChocolateyEnvironmentVariable function -RedirectFrom: - - docs/helpers-uninstall-chocolatey-environment-variable - - docs/helpersuninstallchocolateyenvironmentvariable ---- - -# Uninstall-ChocolateyEnvironmentVariable - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Uninstall-ChocolateyEnvironmentVariable.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -> :choco-info: **NOTE** -> -> Administrative Access Required when `-VariableType 'Machine'.` - -Removes a persistent environment variable. - -## Syntax - -~~~powershell -Uninstall-ChocolateyEnvironmentVariable ` - -VariableName <String> ` - [-VariableType {Process | User | Machine}] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Uninstall-ChocolateyEnvironmentVariable removes an environment variable -with the specified name and value. The variable can be scoped either to -the User or to the Machine. If Machine level scoping is specified, the -command is elevated to an administrative session. - -## Notes - -This command will assert UAC/Admin privileges on the machine when -`-VariableType Machine`. - -This will remove the environment variable from the current session. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -# Remove an environment variable -Uninstall-ChocolateyEnvironmentVariable -VariableName 'bob' -~~~ - -**EXAMPLE 2** - -~~~powershell - -# Remove an environment variable from Machine -Uninstall-ChocolateyEnvironmentVariable -VariableName 'bob' -VariableType 'Machine' -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -VariableName <String> -The name or key of the environment variable to remove. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -VariableType -Specifies whether this variable is at either the individual User level -or at the Machine level. - - -Valid options: Process, User, Machine - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | User -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyEnvironmentVariable](xref:install-chocolateyenvironmentvariable) - * [Set-EnvironmentVariable](xref:set-environmentvariable) - * [Install-ChocolateyPath](xref:install-chocolateypath) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Uninstall-ChocolateyEnvironmentVariable -Full`. - -View the source for [Uninstall-ChocolateyEnvironmentVariable](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Uninstall-ChocolateyEnvironmentVariable.ps1) diff --git a/input/en-us/create/functions/uninstall-chocolateypackage.md b/input/en-us/create/functions/uninstall-chocolateypackage.md deleted file mode 100644 index 666c8046ca..0000000000 --- a/input/en-us/create/functions/uninstall-chocolateypackage.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -Order: 380 -xref: uninstall-chocolateypackage -Title: Uninstall-ChocolateyPackage -Description: Information on Uninstall-ChocolateyPackage function -RedirectFrom: - - docs/helpers-uninstall-chocolatey-package - - docs/helpersuninstallchocolateypackage ---- - -# Uninstall-ChocolateyPackage - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Uninstall-ChocolateyPackage.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Uninstalls software from "Programs and Features". - -## Syntax - -~~~powershell -Uninstall-ChocolateyPackage ` - -PackageName <String> ` - [-FileType <String>] ` - [-SilentArgs <String[]>] ` - [-File <String>] ` - [-ValidExitCodes <Object>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This will uninstall software from your machine (in Programs and -Features). This may not be necessary if Auto Uninstaller is turned on. - -Chocolatey CLI automatically tracks registry changes for "Programs and -Features" of the underlying software's native installers when -installing packages. The "Automatic Uninstaller" (auto uninstaller) -service is a feature that can use that information to automatically -determine how to uninstall these natively installed applications. This -means that a package may not need an explicit chocolateyUninstall.ps1 -to reverse the installation done in the install script. - -With auto uninstaller turned off, a chocolateyUninstall.ps1 is required -to perform uninstall from "Programs and Features". In the absence of -chocolateyUninstall.ps1, choco uninstall only removes the package from -Chocolatey but does not remove the software from your system without -auto uninstaller. - -## Notes - -May not be required. The Automatic Uninstaller (AutoUninstaller) is -turned on by default. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Uninstall-ChocolateyPackage '__NAME__' 'EXE_OR_MSI' 'SILENT_ARGS' 'FilePath' - -~~~ - -**EXAMPLE 2** - -~~~powershell - -Uninstall-ChocolateyPackage -PackageName $packageName ` - -FileType $installerType ` - -SilentArgs "$silentArgs" ` - -ValidExitCodes $validExitCodes ` - -File "$file" -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -PackageName <String> -The name of the package - while this is an arbitrary value, it's -recommended that it matches the package id. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -FileType [<String>] -This is the extension of the file. This should be either exe or msi. - -If what is provided is empty or null, Chocolatey will use 'exe'. - -Property | Value ----------------------- | ------------- -Aliases | installerType -Required? | false -Position? | 2 -Default Value | exe -Accept Pipeline Input? | false - -### -SilentArgs [<String[]>] -OPTIONAL - These are the parameters to pass to the native uninstaller, -including any arguments to make the uninstaller silent/unattended. -[Licensed editions](https://chocolatey.org/compare) of Chocolatey will automatically determine the -installer type and merge the arguments with what is provided here. - -Try any of the to get the silent (unattended) uninstaller - -`/s /S /q /Q /quiet /silent /SILENT /VERYSILENT`. With msi it is always -`/quiet`. Please pass it in still but it will be overridden by -Chocolatey to `/quiet`. If you don't pass anything it could invoke the -installer with out any arguments. That means a nonsilent installer. - -Please include the `notSilent` tag in your Chocolatey package if you -are not setting up a silent/unattended package. Please note that if you -are submitting to the [community repository](https://community.chocolatey.org/packages), it is nearly a requirement -for the package to be completely unattended. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### -File [<String>] -The full path to the native uninstaller to run. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### -ValidExitCodes [<Object>] -Array of exit codes indicating success. Defaults to `@(0)`. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | @(0) -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyPackage](xref:install-chocolateypackage) - * [Install-ChocolateyInstallPackage](xref:install-chocolateyinstallpackage) - * [Uninstall-ChocolateyZipPackage](xref:uninstall-chocolateyzippackage) - * [Get-UninstallRegistryKey](xref:get-uninstallregistrykey) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Uninstall-ChocolateyPackage -Full`. - -View the source for [Uninstall-ChocolateyPackage](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Uninstall-ChocolateyPackage.ps1) diff --git a/input/en-us/create/functions/uninstall-chocolateywindowsservice.md b/input/en-us/create/functions/uninstall-chocolateywindowsservice.md deleted file mode 100644 index eb277b5b2e..0000000000 --- a/input/en-us/create/functions/uninstall-chocolateywindowsservice.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -Order: 375 -xref: uninstall-chocolateywindowsservice -Title: Uninstall-ChocolateyWindowsService -Description: Information on Uninstall-ChocolateyWindowsService function -RedirectFrom: docs/helpers-uninstall-chocolatey-windows-service ---- - -# Uninstall-ChocolateyWindowsService - -> :choco-info: **NOTE** -> -> This function requires a Chocolatey for Business License to use. - -Uninstalls a Windows Service. - -## Syntax - -~~~powershell -Uninstall-ChocolateyWindowsService ` - -Name <string> ` - [<CommonParameters>] -~~~ - - -## Aliases - -None - -## Notes -Requires Chocolatey for Business. - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Name <string> -The name of the service to uninstall. - - -Property | Value ----------------------- | --------------------- -Aliases | -Required? | true -Position? | 0 -Default Value | -Accept Pipeline Input? | true (ByPropertyName) - - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from licensed code. \ No newline at end of file diff --git a/input/en-us/create/functions/uninstall-chocolateyzippackage.md b/input/en-us/create/functions/uninstall-chocolateyzippackage.md deleted file mode 100644 index 25b1ea7e1a..0000000000 --- a/input/en-us/create/functions/uninstall-chocolateyzippackage.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -Order: 390 -xref: uninstall-chocolateyzippackage -Title: Uninstall-ChocolateyZipPackage -Description: Information on Uninstall-ChocolateyZipPackage function -RedirectFrom: - - docs/helpers-uninstall-chocolatey-zip-package - - docs/helpersuninstallchocolateyzippackage ---- - -# Uninstall-ChocolateyZipPackage - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Uninstall-ChocolateyZipPackage.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -Uninstalls a previous installed zip package, may not be necessary. - -## Syntax - -~~~powershell -Uninstall-ChocolateyZipPackage ` - -PackageName <String> ` - -ZipFileName <String> ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -This will uninstall a zip file if installed via Install-ChocolateyZipPackage. -This is not necessary if the files are unzipped to the package directory. - -## Notes - -Not necessary if files are unzipped to package directory. - -This helper reduces the number of lines one would have to remove the -files extracted from a previously installed zip file. -This method has error handling built into it. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Uninstall-ChocolateyZipPackage '__NAME__' 'filename.zip' - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -PackageName <String> -The name of the package - while this is an arbitrary value, it's -recommended that it matches the package id. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -ZipFileName <String> -This is the zip filename originally installed. - -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * [Install-ChocolateyZipPackage](xref:install-chocolateyzippackage) - * [Uninstall-ChocolateyPackage](xref:uninstall-chocolateypackage) - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Uninstall-ChocolateyZipPackage -Full`. - -View the source for [Uninstall-ChocolateyZipPackage](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Uninstall-ChocolateyZipPackage.ps1) diff --git a/input/en-us/create/functions/write-functioncalllogmessage.md b/input/en-us/create/functions/write-functioncalllogmessage.md deleted file mode 100644 index 4fa9a04ab3..0000000000 --- a/input/en-us/create/functions/write-functioncalllogmessage.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -Order: 410 -xref: write-functioncalllogmessage -Title: Write-FunctionCallLogMessage -Description: Information on Write-FunctionCallLogMessage function -RedirectFrom: - - docs/helpers-write-function-call-log-message - - docs/helperswritefunctioncalllogmessage ---- - -# Write-FunctionCallLogMessage - -<!-- This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Write-FunctionCallLogMessage.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). --> - -DO NOT USE. Not part of the public API. - -## Syntax - -~~~powershell -Write-FunctionCallLogMessage ` - [-Invocation <Object>] ` - [-Parameters <Object>] ` - [-IgnoredArguments <Object[]>] [<CommonParameters>] -~~~ - -## Description - -Writes function call as a debug message. - -## Notes - -This function is not part of the API. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -# This is how this function should always be called -Write-FunctionCallLogMessage -Invocation $MyInvocation -Parameters $PSBoundParameters -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -Invocation [<Object>] -The invocation of the function (`$MyInvocation`) - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Parameters [<Object>] -The parameters passed to the function (`$PSBoundParameters`) - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Allows splatting with arguments that do not apply. Do not use directly. - -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - - -[Function Reference](xref:powershell-reference) - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Write-FunctionCallLogMessage -Full`. - -View the source for [Write-FunctionCallLogMessage](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Write-FunctionCallLogMessage.ps1) diff --git a/input/en-us/create/hook-scripts.md b/input/en-us/create/hook-scripts.md deleted file mode 100644 index f9b325dbe2..0000000000 --- a/input/en-us/create/hook-scripts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -Order: 60 -xref: hook-scripts -Title: Hook Scripts -Description: How to use hooks with Chocolatey packages ---- - -Information for using hooks can be found in the [documentation](xref:hooks). \ No newline at end of file diff --git a/input/en-us/create/index.md b/input/en-us/create/index.md deleted file mode 100644 index baae8d9f54..0000000000 --- a/input/en-us/create/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 160 -xref: package-creation -Title: Package Creation -Description: Information about how to create a new Chocolatey package ---- \ No newline at end of file diff --git a/input/en-us/create/package-dependencies.md b/input/en-us/create/package-dependencies.md deleted file mode 100644 index 4efb5bb643..0000000000 --- a/input/en-us/create/package-dependencies.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -Order: 30 -xref: package-dependencies -Title: Package Dependencies in Chocolatey -Description: Understanding Package Dependencies in Chocolatey -RedirectFrom: - - docs/package-dependencies - - docs/PackageDependencies ---- - -# Introduction - -Chocolatey being built on top of a NuGet framework means that we can take advantage of the rich dependency experience that NuGet provides to developers. This allows you to simplify complex application requirements into a single easy-to-use Chocolatey package. - -## Understanding Dependency Syntax - -Dependencies for a particular application are all defined within a package's nuspec file. This file contains _all_ of the metadata about a particular Chocolatey package including: -- Title -- Author -- Version -- Description -- Release Notes, etc - -A `nuspec` _also_ includes a section for defining package dependencies. - -A common example that you'll see across many Chocolatey packages on the [Community Repository](https://community.chocolatey.org/packages) looks like the following: - -```xml -<dependencies> - <dependency id="chocolatey-core.extension" version="1.3.3" /> -</dependencies> -``` - -You will notice in the above sample that there are two elements to a `<dependency />`: -- The `id`, or package name -- An _optional_ `version`. - -If you _do NOT_ provide a version number, Chocolatey will attempt to resolve the dependency to the latest stable release available on the available source(s) per your Chocolatey configuration, or command line you passed. - -In our particular example above the `chocolatey-core.extension` package will resolve at _least_ the 1.3.3 version of the package, unless a newer version is available on your configured source(s). - -### Version Semantics - -Chocolatey follows the NuGet SemVer notation, including exact versions, minimum inclusive, maximum exclusive etc etc. For more information on the available version ranges and their syntax please see the [NuGet SemVer Reference](https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges) documentation available from docs.microsoft.com. - -Additionally, any time you run the `choco new` command to manually build a new Chocolatey Package, the included nuspec template will include information about dependencies and how to use them in the Dependencies section of the file. - -## Understanding how Dependencies are installed - -When a package has a dependency defined, Chocolatey ensures that that dependency is first installed before installing the requested package. For example, you may have a LOB application packaged with Chocolatey that takes a dependency on a particular version of Java Runtime Environment. By defining the specific jre package id and version this LOB application requires, you need only worry about issuing a `choco install LOB -y` command on your target system, and Chocolatey will first check if the dependency is installed, and whether it needs to be upgraded based on the version of the dependency defined. If the dependency is already met, nothing happens, and your LOB application is installed. If the dependency is missing or not the correct version, Chocolatey ensures this _first_ and then installs your LOB application. - -## What you can do with Dependencies and chaining. - -Now that you see how dependencies are defined, their syntax, and how they work, you can start to experiment with things! Perhaps you have a role within your organization that requires a certain list of applications. You could use what is known as a "metapackage" to issue a single `choco install` command, but ensure that _all_ of the required applications are installed. This is done by creating a package for this specific role, and _only including_ a `.nuspec` file. Inside of this nuspec fill out all the required metadata, and list as dependencies all of your required application packages. Chocolatey will do the hard work of ensuring those things are installed when you install this metapackage. - -It is also helpful for very complex packages where a package may take a dependency, which in turn has another dependency. Chocolatey will walk this dependency chain all the way to the beginning, and work backwards until all dependencies are met, and then proceed to install your requested package. - -## Wrapping up - -As you can see dependencies in Chocolatey packages are relatively easy to understand, define, and utilize in your Chocolatey packaging! We encourage you to take advantage of this enhanced functionality in your environments. - -Still have questions? Join our [Discord](Community Chat)! If you're a Chocolatey For Business customer, run `choco support` to see how to get in touch with our support team, who are at the ready to assist you with Package Dependencies! \ No newline at end of file diff --git a/input/en-us/default-chocolatey-install-reasoning.md b/input/en-us/default-chocolatey-install-reasoning.md deleted file mode 100644 index ff90175da7..0000000000 --- a/input/en-us/default-chocolatey-install-reasoning.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -Order: 74 -xref: default-chocolatey-install-reasoning -Title: Default Chocolatey Install Reasoning -Description: Background information on why Chocolatey installs where it does by default -RedirectFrom: docs/default-chocolatey-install-reasoning -ShowInNavbar: false -ShowInSidebar: false ---- - -## <span style="color:red;">NOTICE: As of 0.9.8.24, Chocolatey's default install location is C:\ProgramData\Chocolatey</span> - -This reduces the attack surface on a local installation of Chocolatey and limits who can make changes to the directory. - -You can install Chocolatey to Program Files if you feel that is a more appropriate place. Because Chocolatey has files that change with package installations and it doesn't actually install to Programs and Features (what we consider synonymous with Program Files), we didn't feel this was the appropriate location. Plus with logging currently all in the same location, it would mean you would need to run `choco` with administrative permissions every time, even if you are just doing things like searching for packages, finding out what is installed locally, etc. - -## What about Program Files? Why not default to there? - -You can definitely choose to install to Program Files, however bear in mind that the following considerations apply for you as well. - -1. Files in Program Files are not supposed to change. Data/user data (aka packages) would need to be somewhere else. Most folks put that common user data to ProgramData. Since the Chocolatey files are not much on top of that, everything is there. -2. Program Files is usually, IMHO, reserved for things that are actually system-installed on the machine (like in Program and Features). And again, only what is installed by an installer should go there. All data/packages should go somewhere else, like ProgramData. -3. .NET doesn't handle long paths well. In fact it doesn't handle them at all. We are not much worse off in Program Files, until you consider Program Files (x86). -4. Choco is both x86/x64 - but the applications it installs could be either. Where do those go (this is assuming we shim in "C:\Program Files\Chocolatey\bin" and not to "C:\ProgramData\chocolatey\bin")? Technically x86 apps should never be in "C:\Program Files", they should be in "C:\Program Files (x86)". - -Not saying it is an impossible scenario. It's just generally a difficult scenario to say that's what the default should be without creating confusion and incompatibilities. \ No newline at end of file diff --git a/input/en-us/faqs.md b/input/en-us/faqs.md deleted file mode 100644 index f49e3305e5..0000000000 --- a/input/en-us/faqs.md +++ /dev/null @@ -1,496 +0,0 @@ ---- -Order: 40 -xref: faqs -Title: FAQs -Description: Chocolatey frequently asked questions -RedirectFrom: docs/chocolatey-faqs ---- - -## General - -### Can't find your answer here? - -Feel free to reach out to us on [Chat](https://ch0.co/community-support) or on the [email distribution list / forum](https://groups.google.com/group/chocolatey). - -### What is Chocolatey? - -Chocolatey is kind of like apt-get, but for Windows (with Windows comes limitations). It is a machine level package manager that is built on top of nuget command line and the nuget infrastructure. -[More behind the name](xref:history) - -"Okay, machine package manager, that's nice. What does that mean though?" It means you can simply install software with a few keystrokes and go get coffee while your co-workers are downloading and running an install manually (and I do mean something like an MSI). - -How about updates? Wouldn't it be nice to update nearly everything on your machine with a few simple keystrokes? We think so, too. Chocolatey does that. `choco upgrade all -y` - -### I need a tool that manages software - using scripts to work with those unattended installs. Is that Chocolatey? - -Yes, in a nutshell that is what Chocolatey does. Nearly exactly what you may already be doing, except wrapped up into a package file that allows you to modularize and easily manage order with dependencies on other packages. - -### What is the purpose of Chocolatey? - -Great question! See [The purpose of Chocolatey](xref:why#what-is-the-purpose-of-chocolatey) - -### How does Chocolatey work? - -See [What is Chocolatey?](xref:why#what-is-chocolatey) - -### Why Chocolatey? - -First a [story](xref:chocolatey-story). Then [Why Chocolatey](xref:why) - -### Can I use Chocolatey at my organization? - -Absolutely! The licensing is very business friendly (plus we have [paid options](https://chocolatey.org/compare) to better help organizations - *hint, hint*). We typically recommend organizations depending Chocolatey look to managing their own packaging as opposed to using the Community Package Repository (https://community.chocolatey.org/packages) - packages there are not 100% reliable due to distribution rights with publicly available packages (which causes a major failure point). See the next question for details. - -### Are you redistributing software? - -No. Packages on Chocolatey's community repository (https://community.chocolatey.org/packages) are publicly available and as such they are subject to software distribution rights. With those packages the following applies: - -> Chocolatey does the same thing that you would do based on the package instructions. This usually means going out and downloading an installer from the official distribution point and then silently installing it on your machine. With most packages this means Chocolatey is not redistributing software because they are going to the same distribution point that you yourself would go get the software if you were performing this process manually. - -To put it another way, Microsoft would be quite upset if the Office 365 packages on the community repository actually contained the Office 365 binaries. This is not something organizations would be subject to when hosting their own internal package. - -When you host internal packages, those packages can embed software and/or point to internal shares. You are not subject to software distribution rights, thus you can create packages that are more reliable, offline, and secure. See [What are Chocolatey Packages](xref:getting-started#what-are-chocolatey-packages) for more details. - -For more information on organizational cautions about the community package repository, see [the community repository disclaimer](xref:community-packages-disclaimer). - -### Where does Chocolatey install by default? - -As of version 0.9.8.24, binaries, libraries and Chocolatey components install in ```C:\ProgramData\chocolatey``` (environment variable %ProgramData%) by default. This reduces the attack surface on a local installation of Chocolatey and limits who can make changes to the directory. - -> :choco-info: **NOTE** -> -> Historically, Chocolatey installed to ```C:\Chocolatey``` and currently, performing an update of Chocolatey doesn't change the installation location, except for when the install path is `C:\chocolatey`. It will upgrade that path and all variables automatically. For more information about why Chocolatey used ```C:\Chocolatey``` as the default location, look here - [Default Install Reasoning](xref:default-chocolatey-install-reasoning) - -### What kind of package types does Chocolatey support? - -* Binary Packages - Installable/portable applications - This is 98% of the Chocolatey packages - most are pointers to the real deal native installers and/or zipped software. -* PowerShell Command Packages - Packages that have the suffix **.powershell** will install PowerShell scripts as commands for you to call from anywhere. -* Development Packages - Packages that have the suffix **.dev**. For instance [dropkick.dev](https://www.nuget.org/packages/dropkick.dev). -* Roadmap - Virtual Packages - Packages that are like a category, and you just want one package from that category. [Read more …](https://github.com/chocolatey/chocolatey/issues/7) - -### Do you have a roadmap I can see? - -We do, take a look at the [roadmap](xref:roadmap) - -## Security - -### Is Chocolatey secure? - -Yes, it is. You can read more at [security](xref:security) to understand the important details. - -### Why do I have to confirm packages now? Is there a way to remove this? - -tl;dr - Yes, completely possible. Use `-y` or turn on `allowGlobalConfirmation`. - -Also check out the help menus now - `choco -h`, `choco install -h` - -Longer answer, we've moved a little closer towards other package managers for security reasons, where by default we stop and confirm if you are okay with the state change. We always communicate changes in the [release notes](xref:floss-release-notes), so we highly recommend folks scan at least one of those to see anything tagged breaking changes. Always scan from your current version up to the one you are upgrading to so that you catch all changes. - -The one that is the most important right now is the `x.y.z` release (in this case 0.9.9), once we reach v1 we will be fully SemVer compliant and breaking changes will constitute a major version bump (we're still SemVer in a less than v1), so you can scan breaking changes and major new features in an `x` release, new compatible features in a `.y` release, and `.z` releases will only contain compatible fixes for the current release. - -0.9.9 introduced a new compiled client that was/is a total rewrite. 0.9.10 will have complete feature parity with the older client - see [FeatureParity](https://github.com/chocolatey/choco/labels/FeatureParity). Why the rewrite? For a more maintainable, faster client that can run on mono now, so you are not completely tied to Windows. We've started adding support for other install providers (like [Scriptcs](https://github.com/chocolatey/choco/issues/247)). - -The [relevant bits of the release notes](xref:floss-release-notes#099-march-3-2015) for the FAQ: - - - [Security] Prompt for confirmation: For security reasons, we now stop for confirmation before changing the state of the system on most commands. You can pass `-y` to confirm any prompts or set a value in the config that will globally confirm and behave like older versions of Chocolatey (`allowGlobalConfirmation`, see `choco feature -h` for how to enable). - -Some folks may find the change quite annoying. The perspective of some folks isn't the perspective of everyone and we have some very security-conscious folks that want a verification of what they requested is what they end up with. So this prompt is extremely important for them. We are moving to a more secure by default approach so this change was important to get us there. Security related changes are some of the only things you will see that affect Chocolatey in such a way. - -We spent many months stressing over this change because of the breaking part and decided it wasn't going to get easier to change later. We've added the ability for you to set Chocolatey back to the way it was before with `allowGlobalConfirmation` and if the prompts annoy you, you should probably look at making this change. - -### What doesn't the website implement x security standard? - -While we keep up with most security aspects, sometimes we miss things. Always feel free to reach out to us if you feel there is something we should implement to make that better. - -### I have other security questions - -Please see [security](xref:security). Please reach out to us if you cannot find answers to what you are looking for. - -## Using Chocolatey - -### Can I use Chocolatey in a cmd.exe shell? - -Yes, Chocolatey has some official clients, one of which is `choco.exe` and it is a command line tool, so it works equally well in Powershell.exe and cmd.exe. However if you have the PowerShell profile installed, you also get tab completion in Powershell.exe. - -### Tab-completion? - -See the [troubleshooting](xref:troubleshooting) page if `choco <tab>` doesn't work for you when you are using PowerShell. - -### What is the difference between Open Source Chocolatey, Chocolatey Pro, and Chocolatey for Business? - -Great question, we have a comparison table listed at [compare](https://chocolatey.org/compare). There is also an FAQ section related specifically to licensing. - -### I'm interested in C4B (Chocolatey for Business) but I have questions. - -Please see [licensed editions](#licensed-editions) section below. - -### Does Chocolatey require administrative permissions to run? - -It does by default - based on where it is installed. However there is an non-administrative installation for Chocolatey under More Options at [installation](xref:setup-choco). Do keep in mind that there is pass through to what packages are doing that makes a determination for whether the package needs administrative permissions, and Chocolatey works within the context of Windows permissions, so you are not going to get around that (aside from what is provided with self-service, see question below). - -### I would like to be able to offer my non-admin desktop users an option for self-service type of installations. - -Yes, we absolutely support that scenario in Chocolatey for Business. See [Licensed Editions](#licensed-editions) for more information. - -### Can I use Chocolatey with existing installs? - -Fantastic question, see [Can I use Chocolatey with existing software?](xref:why#can-i-use-chocolatey-with-existing-software) - -### What is the default package source repository URL (community feed url)? - -That would be https://community.chocolatey.org/api/v2/ aka the Community Package Repository. - -### What can I install? - -You can package and install anything on Windows using Chocolatey - if it can be automated, Chocolatey and PowerShell can install, upgrade, and uninstall it. - -However, if you are just curious on what is available in the community, check out the community package repository at https://community.chocolatey.org/packages. Note that it does have one large limitation, distribution rights, which makes the community package repository not fully reliable like an internal repository which is not subject to distribution rights. - -You can also install packages from other sources (nuget.org, rubygems.org, web pi tools, etc). - -### What if I install X and I already have X installed? - -With most packages when you already have something installed, the Chocolatey process will just perform the install again silently. Most times this means that it does nothing and in the end you have what you already had. - -### Can I override the installation directory? - -Yes you can, see [Overriding install directory](xref:getting-started#overriding-default-install-directory-or-other-advanced-install-concepts) and [Ubiquitous Install Directory Option](xref:install-directory-override). - -### What distinction does Chocolatey make between an installable and a portable application? - -#### Installable application - -An installable application is something that comes with a native installer and ends up in the add/remove programs (in control panel of the system). -Installable applications end up where the native installer wants them to end up (i. e. Program Files). If you want to override that, please feel free to with the proper commands using InstallArgs (-ia) at the command line and possibly override - Install Command. Yes this does mean you will need to have intimate knowledge of the installer. Having Chocolatey itself make the override directory is likely at some point, but it is wwwwaaaaayyyy out on the radar (like after Rob is somehow paid to work on Chocolatey full time ;) ). - -#### Portable application - something that doesn't require a system install to use - -A portable application is something that doesn't require a native installer to use. In other words, it is not "installed" on your system (where you can go to uninstall in the control panel). It also requires no administrative access for the package install. - -Portable applications end up in the %ChocolateyInstall%/lib (i. e. C:\ProgramData\Chocolatey\lib) folder yes, but they get a "shim" to put them on the path of the machine. This behavior is very much to how Chocolatey works and is not configurable (the directory). Where the portable apps end up is still going to be %ChocolateyInstall%/lib no matter where you move the directory, unless a package itself unpacks the portable app elsewhere (as in the case of [git-tfs](https://community.chocolatey.org/packages/gittfs)). - -### Why doesn't a package install software to Program Files? - -Most packages that use native installers (MSI, InnoSetup, etc) will install to Program Files, but there are packages that do not. There are two really important reasons why: - -* Program Files is synonymous with software that has uninstall registry keys - or put another way, applications that have native installers that you can find for uninstall in the Control Panel under Programs and Features. -* Writing to Program Files requires administrative permissions and the package you are installing is likely a portable package (even if not explicitly named so, it may have a zip that it extracts). There is also a way for non-administrators to use Chocolatey and these types of packages need to work for them as well. - -It really depends on the underlying software the package "installs". If the underlying software is a native installer, then it has a machine install (meaning it gets an uninstall registry key and shows up in Programs and Features) and Program Files is the appropriate place for it. - -Chocolatey has a different avenue for portable packages that allows both admins and non-admins to be able to use these packages, after all they are just downloading and unzipping an archive. These packages either go into a Tools Root location or just get shims (executables are put on the path) and continue to stay in the Chocolatey lib directory. If we restricted a non-admin for an avenue that would work for them manually, it wouldn't make choco useful for them at all. Since we support non-admin usage of Chocolatey, packages that can support the portable model should support it. - -Also consider that if the package **is** using `$env:ChocolateyBinRoot` (which will later be named `$env:ChocolateyToolsRoot`) you can set the root under Program Files and then you get the better of both worlds. - -### What is the difference between packages no suffix as compared to *.install *.portable? - -What is the difference between packages named *.install (i. e. [autohotkey.install](https://community.chocolatey.org/packages/autohotkey.install)), *.portable (i. e. [autohotkey.portable](https://community.chocolatey.org/packages/autohotkey.portable)) and * (i. e. [autohotkey](https://community.chocolatey.org/packages/autohotkey))? - -tl;dr: Nearly 100% of the time, the package with no suffix (autohotkey in this example) is going to ensure the *.install. The package without the suffix is for both discoverability and for other packages to take a dependency on. - -Hey, good question! You are paying attention! Chocolatey has the concept of virtual packages (coming, please see [GitHub Issue](https://github.com/chocolatey/choco/issues/858)) and meta packages. Virtual packages are packages that represent other packages when used as a dependency. Metapackages are packages that only exist to provide a grouping of dependencies. - -A package with no suffix that is surrounded by packages with suffixes is to provide a virtual package. So in the case of git, git.install, and git.commandline (deprecated for .portable) - git is that virtual package (currently it is really just a metapackage until the virtual packages feature is complete). That means that other packages could depend on it and you could have either git.install or git.portable installed and you would meet the dependency of having git installed. That keeps Chocolatey from trying to install something that already meets the dependency requirement for a package. - -Talking specifically about the *.install package suffix - those are for the packages that have a native installer that they have bundled or they download and run. - -> :choco-info: **NOTE** -> -> The suffix *.app has been used previously to mean the same as *.install. But the *.app suffix is now deprecated and should not be used for new packages. - -The *.portable packages are the packages that will usually result in an executable on your path somewhere but do not get installed onto the system (Add/Remove Programs). Previously the suffixes *.tool and *.commandline have been used to refer to the same type of packages. - -> :choco-info: **NOTE** -> -> Now *.tool and *.commandline are deprecated and should not be used for new packages. - -#### Video Explanation - -Below is a video detailing the reasoning and intention behind the use of the different package naming suffixes used on the Chocolatey Community Repository. - -<div class="ratio ratio-16x9 mb-3"> - <iframe src="https://www.youtube.com/embed/aYnDDBDaAj0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen> - </iframe> -</div> - -### When I install a portable app like autohotkey.portable, how is it on my path? Without littering my path? - -When you install portable apps that have executables in the package, Chocolatey automatically creates a "shim" file and puts that in a folder that is on the path. That allows you to run a portable application by asking for it on the command line. - -When you take an application with a native installer, say like WinDirStat, it is only on your path if the native installer has put it there or the instructions in the Chocolatey package itself has requested for it to be on the path. In this case, this is the "littering" the path concept. - -### Is there a PowerShell Module for Chocolatey? - -There is not any official ones from Chocolatey Software. If and when there is, it will be provided as a binary DLL likely. - -The main Chocolatey client (choco.exe) is an executable client that has runs a PowerShell host in proc and has a PowerShell module it loads for those PowerShell automation scripts. Trying to get all of these ideas into a higher PowerShell module could be kind of difficult. - -Even through it was originally written *in* PowerShell, **Chocolatey was NEVER a PowerShell module, it just used PowerShell as a programming language and was meant to be a CLI app.** I bolded this so it might get read twice. ;) - -A little history - Chocolatey up until 0.9.9 was provided completely written in PowerShell, with the approach above. We know of no other app/tool that tried this approach when we did, which made the original Chocolatey client a rarity indeed. It paved the way for things like mocking in [Pester](https://github.com/pester/Pester) ([Matt Wrock](https://github.com/mwrock) [added mocking](https://github.com/pester/Pester/compare/b103a3db951f123c485289f02eaa1d6ef686c21b...4178c343a6574a8a9521be8a77006572fc49e311) after [Rob Reynolds](https://github.com/ferventcoder) [determined](https://github.com/chocolatey/chocolatey/commit/5b2887240dfbda86629d6a1a296129f3a561e86a#diff-b61a6d542f9036550ba9c401c80f00ef) [the](https://github.com/chocolatey/chocolatey/commit/cc4aca0dc48840c7113167bd08aeddcaf83f65c0#diff-b61a6d542f9036550ba9c401c80f00ef) [general way](https://github.com/chocolatey/chocolatey/commit/ee883242c962dc886cd1282e4dbe4121d4fcc6cd#diff-b61a6d542f9036550ba9c401c80f00ef) [it works](https://github.com/chocolatey/chocolatey/commit/654703b9d4388eb385776986ce6d0ee53485a146#diff-b61a6d542f9036550ba9c401c80f00ef) in PowerShell back in 2012). - -### Does Chocolatey run on macOS/Linux? - -Yes, for creation and maintenance of packages. See [running on non-Windows](xref:non-windows) for more information. - -## Troubleshooting - -### I'm running into some issue with Chocolatey, packaging, or something else. - -See [Troubleshooting](xref:troubleshooting) - -## Organizational Use - -### I would like to use Chocolatey in my organization, is the licensing friendly? - -Yes, it is. Chocolatey carries a FOSS Apache 2.0 license, which is extremely business friendly. You can use Chocolatey and most of its infrastructure completely free. Chocolatey also has a business edition with features organizations need for better software management . See [Compare](https://chocolatey.org/pricing) for details. - -### Should my organization depend on (use) the community feed (https://community.chocolatey.org/packages)? - -For production-level scenarios, I couldn't justify giving up that level of control and trust to the internet in an organization. It's recommended that you copy and modify existing packages and/or create your own internal packages and host them internally. That way you can completely guarantee that an install/upgrade/uninstall will always work every time. See [Security](xref:security#chocolateyorg-the-community-feed) for more details. - -If you are just setting up or updating developer workstations and can tolerate things breaking every once in awhile because internet/uncertainty, it's fine to use the community feed. - -### Chocolatey is great! I need it to do something additional for my organization. - -Please see https://chocolatey.org/compare - we may already support it doing that for the business edition. If not, feel free to reach out to our team. - -Also see the [Licensed Editions](#licensed-editions) section below. - -## Licensed Editions - -### What is the difference between FOSS and the licensed editions? - -A lot of that is covered in the FAQ on the [pricing](https://chocolatey.org/pricing#faq), but also be sure to check out the [comparison table](https://chocolatey.org/compare). - -### Are the licensed editions costs annual? - -They are, but we can also do multi-year contracts (with full amount paid on contract acceptance) if you need to support something closer to that model. We also have a perpetual for Chocolatey for Business. For more detail, please see the [pricing FAQ](https://chocolatey.org/pricing#faq). - -### Can you do monthly? - -Not at this current time. Please see the [pricing FAQ](https://chocolatey.org/pricing#faq) for more details. - -### What is C4B? - -That is the short name for Chocolatey for Business. - -### I have not received my license. - -The license email is sent from a support email at chocolatey dot io with an xml file (the license) attachment within 1-3 business days. If it has been 3 business days and you have not received your business license, please reach through the [sales contact](https://chocolatey.org/contact) (choose "Other") (or any method you may already have for contacting sales) to get this resolved. - -Any number of things could have happened: - -* The message could be block by your servers -* The message could be misidentified as spam - -To reduce these kind of occurrences, please make sure you have whitelisted the following email domains: - -* `chocolatey.io` -* `chocolatey.org` - -Once you receive a few emails from there, it will give you an idea of how to lock that down further to fewer email addresses. - -### I just purchased and I need my license sooner! - -Just reply to the order email you receive and let us know so we can bump the priority of your order. - -### I have a different question about the licensed edition. - -Check out the FAQ on the [pricing](https://chocolatey.org/pricing#faq). If it doesn't answer your questions, please feel free to reach out to the sales team from there! - -## Packaging - -### What can a Chocolatey Package consist of? - -See [What are Chocolatey Packages?](xref:getting-started#what-are-chocolatey-packages) - -### Tell me about packaging - -Chocolatey packages are what we like to think of as just fancy zip files. Zip files that have package metadata about the package and the underlying software a package may represent, dependencies, and optional binaries, files, and/or optional PowerShell automation scripts. - -### How do I create packages? - -Try running `choco new test` from a command shell and inspect the output. You will find quite a bit of helpful information and just in time documentation in there. - -### I'm creating packages with the software contained in the package. - -Great! This is the most reliable use of Chocolatey, to embed the binaries directly in the package. See the next question for more details. - -### I'm creating internal or offline packages, what do I need? - -Well, if you are not creating packages for the community package repository, you have different rules that apply. Embed as much as possible into the package (as long as it is under 500MB you should see no issues). We typically recommend 500MB as the threshhold for organizations for the following reasons: - -* a nupkg file size takes up some space -* files in the package directory (can be cleaned up as part of the script) -* the actual install location if using an installer -* MSI cache for MSIs - Windows caches the complete MSI binaries (and now you know where all that space went) - -If you are on a licensed edition of Chocolatey, you can turn on Package Reducer and the first two items above no longer take up any significant space. This can reduce space usage in the order of GBs for some installations of Chocolatey. See [Package Reducer](xref:package-reducer) for more details. - -### The install location displayed is incorrect or missing. - -For packages that run installers, this can be be caused by the installer not setting its install location. -For portable packages, it can be caused by not using the built in archive PowerShell helpers (e.g. because the software is not inside an archive) or by moving the extracted files after using an archive helper. - -The install location which is displayed can be manually set in the `ChocolateyInstall.ps1` with the `$Env:ChocolateyPackageInstallLocation` environment variable. - -If you are setting this variable in an installer package, do not hard code it, but instead get the location via checking the uninstall keys in the registry or similar. -If this is hard coded for a package that runs an installer, it may display an incorrect location if the install location is changed manually, by install arguments, or via the licensed ubiquitous install directory switch. - -### How do I skip the Automatic Uninstaller? - -If you are trying to uninstall a package, but Automatic Uninstall is uninstalling software you don't want uninstalled, or otherwise misbehaving, then it can be skipped by using the `--skip-autouninstaller` switch, or disabling it by setting the `autoUninstaller` feature to `false`. - -If you are creating a package, and want or need to use the `chocolateyUninstall.ps1` while not running the Automatic Uninstaller, then include a `.skipAutoUninstall` file inside the package. If a file with that name is found, then during uninstall the Automatic Uninstaller will not be run. If a `.skipAutoUninstall` file is being included, make sure that it is included in the `files` element of the `.nuspec`, either explicitly via a `file` element, or by placing the file inside a folder that is included inside the package (like the `tools` directory). - -## Videos / Reference - -### Where can I learn more? - -We have a documentation section of the site at https://docs.chocolatey.org - -### Do you have any references or videos I can see? - -Yes we do, take a look at [videos](xref:videos) and [known posts, presentations, etc](xref:resources). - -### Is there a video I can watch to show me Chocolatey in action? - -There is! This is a long video due to slow internet connections, but watch the first 1:30ish minutes and the last 1:30ish minutes and that will give you a general idea. [https://www.youtube.com/watch?v=N-hWOUL8roU](https://www.youtube.com/watch?v=N-hWOUL8roU) - -> :choco-info: **NOTE** -> -> This video shows dependency chaining, so you are seeing it install 11 applications/tools. It's also 6+ years old and there have been many, many improvements since then. - -## Community Package Repository - -### I just took over as the primary maintainer of a package. What do I need to do? -See [Package Maintainer Handover](xref:package-maintainer-handover) - -### What is moderation? - -Related to the community package repository only (aka the default feed aka https://community.chocolatey.org/packages), we have a concept called moderation, where submitted packages are held until they are considered safe and of minimal quality for regular consumption. - -Moderation involves checking a package version for quality (validation) and correctness, whether it installs and uninstalls correctly (verification). We have two automated services that validate and verify packages. The validator checks the quality of a package. If no requirements are flagged as failing review, it will be passed on to the verifier, which checks that the package actually works as intended (it may help to think of the validator as unit testing and the verifier as integration testing). If both of these automated reviews pass the package version is submitted to a moderator for final review and approval. - -Things to note: - -* We have trusted packages, and those packages skip human review/moderation. -* A maintainer can not moderate his/her own pkgs. -* You can see if a package has been verified by the green circle next to its name on the package page. If it is green or red, it will also be a clickable link. To see all packages verified, see https://gist.github.com/choco-bot -* Besides trusted packages, a package version is never approved without a moderator clicking approve. - -### How does the moderation review process work? - -See [Review Process](xref:moderation#package-review-process). - -### What is a trusted package? - -Related to the community package repository only (aka the default feed aka https://community.chocolatey.org/packages). - -A package that is considered trusted comes from the original software creator or is maintained by someone in the community who has a track record for high quality and safe packages. - -Two ways your packages can become trusted: - -* You write the underlying software that the package installs. For instance the ReSharper package that comes directly from JetBrains. -* You put in a lot of good packages and your packages will eventually become trusted. - -In most cases, a package will only be switched to trusted after a few versions have been approved by moderators without any changes being required. This is to ensure that the package has been looked at by more than one person, since automated testing does not catch everything. Switching a package to trusted status is a manual change by a moderator. It is not an automated process, and does not happen imediately even if you are the software author. - -> :choco-info: **NOTE** -> -> All packages go under automated verification, validation and virus scanning. If any of the tests don't pass, they are held for the maintainer to fix the package or to make a review comment. This includes trusted packages. - -### How do I install a package version under moderation? - -Related to the community package repository only (aka the default feed aka https://community.chocolatey.org/packages). - -You can install a version of a package version that's still under moderation - however know that if the maintainer needs to fix the package version during the review process, you will never get those fixes locally since they are updating the **SAME** version. Package versions are not immutable until they are approved. The caveat for "never" is that if you know it changed (likely you won't and there is no notification, *what you have installed technically never existed*), you could force the reinstall of that same version of the package. - -Another thing to consider: if the package version or the package as a whole is rejected (usually for renaming the package to something better to better meet naming standards), you are likely to get weird warnings later and won't see updates at all. Remember, you have installed something that technically never existed, so any thing you see related to choco not knowing about it is to be expected and not a bug. - -To actually install, see the next question. - -### How do I install an unlisted package / package version? - -You need to specify name AND version to any package to install the unlisted/unapproved version. This goes for any NuGet compatible feed that understands unlisted packages. - -### How do I install a rejected package? - -Related to the community package repository only (aka the default feed aka https://community.chocolatey.org/packages), we have a concept of packages that have been rejected. You cannot install a rejected package. It could do bad things to your system so we don't allow install from the community repository. - -### How do I self-reject a package? - -> :choco-info: **NOTE** -> -> This applies during the moderation process only on the community repository. Once approved, there is no reject. - -If you are a maintainer of a package and you would like to self-reject an older version of a package that is failing verification or validation, we support that. If however you just want to reject a working package because it is older, we don't support that. Rejected != Obsolete. It's really about when the underlying software has the same download url for every release so the older versions do not apply. If you are using checksums to verify the download (and you should be), then your older versions should start failing. - -![Reject package checkbox is only visible if the package has failed automated review](/assets/images/faqs/package-moderation-reject-package.png) - -* Failing verification - - -![An example email which is sent to maintainer of package when an automated check has failed](/assets/images/faqs/email-from-validator.png) - -* Failing validation - a message from the validator telling you it failed validation. - -### What is the validator? - -The [validator](xref:package-validator) is a service that checks the quality of a package based on requirements, guidelines and suggestions for creating packages for Chocolatey's community feed. Many of the validation items will automatically roll back into choco and will be displayed when packaging a package. We like to think of the validator as unit testing. It is validating that everything is as it should be and meets the minimum requirements for a package on the community feed. - -What does the validator check? See the [validator docs](xref:package-validator). - -### What is the verifier? - -The [verifier](xref:package-verifier-service) is a service that checks the correctness (that the package actually works), that it installs and uninstalls correctly, has the right dependencies to ensure it is installed properly and can be installed silently. The verifier runs against both submitted packages and existing packages (currently checking once a month that a package can still install and sending notice when it fails). We like to think of the verifier as integration testing. It's testing all the parts and ensuring everything is good. On the site, you can see the current status of a package based on a little colored ball next to the title. If the ball is green or red, the ball is a link to the results (only on the package page, not in the list screen). - -![Passing verification](/assets/images/faqs/verification-successful.png) - -* Green means good. The ball is a link to the results -* Orange if still pending verification (has not yet run). -* Red means it failed verification for some reason. The ball is a link to the results. -* Grey means unknown or excluded from verification (if excluded, a reason will be listed on the package page). - -### What is the package scanner? - -All packages (and the binaries they contain or download at runtime) on community repository are scanned by 50-60 antivirus scanners. We have partnered with [VirusTotal](https://virustotal.com) to provide this information back to the website so you can know when you are on a package page whether it is something you should be concerned with or not. It falls just under the files section of the package pages. - -> :choco-info: **NOTE** -> -> Only en-US installers are tested by default via Chocolatey's Package Scanner - -> :choco-info: **NOTE** -> -> Did you know that 60% or more of the sofware that is submitted to the community repository has its first scans by VirusTotal through Chocolatey's package scanner submissions? It's helped many of those anti-virus manufacturers get a clearer picture of heuristics and hopefully ends up in better anti-virus products with less false positives. - -> :choco-info: **NOTE** -> -> Need runtime malware protection? Learn more about [runtime malware protection](xref:virus-check) - -### What is the package cacher? - -On the community repository, we have a CDN cache for those files that would be downloaded by packages - those remote urls are overridden by default in licensed editions of Chocolatey to use those cached binaries. This is to avoid 404 errors you would normally see if those urls changed or were removed. See [Customer CDN Download Cache](xref:private-cdn) for more details. - -## Comparison - -### How is Chocolatey different than OneGet/PowerShell Package Management? - -OneGet is a package manager **manager**, which means it is not really a package manager at all. Chocolatey will have a provider that plugs right into OneGet. At the current time there is a CTP available, but it is based on 2 year old Chocolatey technology (we've had security fixes since then, plus a world of features), so we can't really recommend it. But if you must use it, make sure your PowerShell execution policy is set correctly and you are in an administrative console. See https://www.hanselman.com/blog/aptget-for-windows-oneget-and-chocolatey-on-windows-10 for more details. - -Use ChocolateyGet for now. - -### How is Chocolatey different than Ninite? - -Great question, see [Chocolatey vs Ninite](xref:chocolatey-vs-ninite). - -### How is Chocolatey different than NuGet and/or OpenWrap? - -Chocolatey is a machine package manager. Where NuGet/OW are focused on developer library packages, Chocolatey is focused on applications and tools, and not necessarily developer focused. - -A typical way of stating the difference is "Developers use NuGet to get 3rd party libraries that they use to build the .NET tools and applications that they release with Chocolatey!" - -### How is/will Chocolatey be different than apt? - - * Chocolatey does not support the idea of source packages, which are packages that must be built to be used. For someone interested in that, check out https://github.com/Microsoft/vcpkg. - * Library packages are not completely off the plate, but mostly. How would you link the library up to the application/tool? diff --git a/input/en-us/features/branding.md b/input/en-us/features/branding.md deleted file mode 100644 index b240407570..0000000000 --- a/input/en-us/features/branding.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -Order: 150 -xref: branding -Title: Branding Chocolatey Applications (C4B) -Description: Brand Chocolatey applications with your own organisational icons -RedirectFrom: docs/features-branding ---- - -We are aware that some of customers want to be able to brand Chocolatey GUI so -that is "looks" like their own internal applications. Out of the box, Chocolatey -GUI's main screen looks like this: - -![Chocolatey GUI Main Screen](/assets/images/gui/main-screen.png) - -However, with branding applied, Chocolatey GUI's main screen can instead look like -this: - -![Chocolatey GUI Main Screen with Branding](/assets/images/gui/main-screen-with-branding.png) - -Here, the logo of a company called A Squared Software Ltd is being used, instead -of the main Chocolatey logo. In addition, a _Powered By Chocolatey_ logo is added -to the bottom left corner of the application. - -## Requirements for branding - -> :choco-info: **NOTE** -> -> Branding of Chocolatey GUI is only available to our Business -License customers, and requires the **Chocolatey GUI Licensed Extension** -(chocolateygui.extension) to be installed, alongside Chocolatey GUI. - -In order for branding to work, there are a number of image files that are required. -These have to be named exactly as the following: - -* icon_256x256.ico -* logo_150x250.png -* splash_700x302.png -* splash_975x421.png -* splash_1250x540.png - - -> :choco-info: **NOTE** -> -> The reason that there are multiple splash screen images is because -Chocolatey GUI makes a decision, based on the resolution of the screen, which -splash screen image to display to the user. - -The numbers in the file names are a suggestion as to the width and height of each -image. While the images don't have to _exactly_ match these dimensions, it is -recommended that they are as close as possible to these dimensions. - -## Location of branding files - -In order for your custom branding files to be applied, you must place the above -files into one of two specific places. - -### Default Location - -By default, Chocolatey GUI will look for custom branding files in the Chocolatey -installation directory (normally `c:/programdata/chocolatey`), and then in a folder -called `branding/gui`. i.e. it will look in the following folder: - -`c:/programdata/chocolatey/branding/gui` - -### Custom Location - -It is possible to use a custom location by first settings an environment variable -called `ChocolateyBrandingLocation` to a new location. For example, if you created -this environment variable with a value of `c:/temp/branding`, then Chocolatey GUI -would then expect to find the above asset files in this location: - -`c:/temp/branding/gui` - -## ChocolateyGuiBranding.dll - -The first time Chocolatey GUI, with the Chocolatey GUI Licensed Extension installed, -is executed, and the above asset files are in one of the defined locations, a new -file will be generated in the same location called `ChocolateyGuiBranding.dll`. -The new file actually contains all the image files that were created, as they have -been embedded as resources within this assembly file. This approach is used in -order to optimize the loading of the assets. Once this ChocolateyGuiBranding.dll -has been created, Chocolatey GUI will use it each time the application runs. The -original image asset files are actually no longer required, and can be removed. -If at any point you need to re-generate the branding that is being used, simply -delete the following two files: - -* ChocolateyGuiBranding.dll -* ChocolateyGuiBranding.resources - -Then update, your image asset files, and re-run Chocolatey GUI and the branding -assembly will be re-generated. - -Using a single ChocolateyGuiBranding.dll as the source of branding makes it very -simple to generate and distribute this assembly to apply branding across your -entire organisation. - -## Branding in action - -The below GIF shows the default opening of the Chocolatey GUI application when -there is no branding applied. - -![Chocolatey GUI in action](/assets/images/gui/in-action.gif) - -In this GIF, we see branding being applied to the Chocolatey GUI application. - -![Chocolatey GUI in action with branding](/assets/images/gui/in-action-with-branding.gif) - -Notice that the splash screen image has been replaced, as well as the logo at the -top left of the application, and the icon in the taskbar. - -> :choco-info: **NOTE** -> -> There is an open issue regarding the icon in the taskbar not -being correctly replaced, visit https://github.com/chocolatey/chocolatey-licensed-issues/issues/157 -for more information. - -> :choco-info: **NOTE** -> -> To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b. - -## Deploying Branding - -What follows is a suggestion on how a branded version of Chocolatey GUI can be -deployed out to your environment. - -> :choco-info: **NOTE** -> -> In order for the below to work, you must have the Chocolatey GUI Licensed -> Extension (`chocolateygui.extension`) installed. You can run `choco download chocolateygui.extension --internalize` -> to download the package and then publish it to your repository. - -1. Follow the steps above to place the branding image assets into the correct location. -1. Run the Chocolatey GUI application to generate the ChocolateyGuiBranding.dll -1. Create a new folder on your file system to house the branding Chocolatey Package -1. In this folder, create a `tools` folder -1. Copy the generated `ChocolateyGuiBranding.dll` into this folder -1. Copy the following xml into a file called `chocolateygui-branding.nuspec`. - - <?xml version="1.0" encoding="utf-8"?> - <package xmlns="http://schemas.microsoft.com/packaging/2015/06/nuspec.xsd"> - <metadata> - <id>chocolateygui-branding</id> - <version>0.1.0</version> - <title>chocolateygui-branding (Install) - __REPLACE_AUTHORS_OF_SOFTWARE_COMMA_SEPARATED__ - https://_Software_Location_REMOVE_OR_FILL_OUT_ - chocolateygui-branding SPACE_SEPARATED - __REPLACE__ - __REPLACE__MarkDown_Okay - - - - - - - - - - -1. Copy the following PowerShell into a file called `tools\chocolateyInstall.ps1` - - $toolsDir = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)" - $helpersFile = Join-Path -Path $toolsDir -ChildPath 'helpers.ps1' - - . $helpersFile - - $chocolateyGuiBrandingAssembly = Join-Path -Path $toolsDir -ChildPath 'ChocolateyGuiBranding.dll' - $chocolateyGuiBrandingLocation = Join-Path -Path (Get-BrandingLocation) -ChildPath 'gui' - - if(!(Test-Path -Path $chocolateyGuiBrandingLocation)){ - New-Item $chocolateyGuiBrandingLocation -ItemType Directory -Force | Out-Null - } - - Copy-Item -Path $chocolateyGuiBrandingAssembly -Destination $chocolateyGuiBrandingLocation - -1. Copy the following PowerShell into a file called `tools\chocolateyuninstall.ps1` - - $toolsDir = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)" - $helpersFile = Join-Path -Path $toolsDir -ChildPath 'helpers.ps1' - - . $helpersFile - - $chocolateyGuiBrandingLocation = Join-Path -Path (Get-BrandingLocation) -ChildPath 'gui' - $chocolateyGuiBrandingAssembly = Join-Path -Path $chocolateyGuiBrandingLocation -ChildPath 'ChocolateyGuiBranding.dll' - - Remove-Item -Path $chocolateyGuiBrandingAssembly -Force -ErrorAction Continue | Out-Null - -1. Copy the following PowerShell into a file called `tools\helpers.ps1` - - function Get-BrandingLocation { - <# - .SYNOPSIS - Gets the top level location for branding files used by Chocolatey - applications - .DESCRIPTION - Creates or uses an environment variable that a user can control to - communicate with packages about where they would like branding files to - be located. - .NOTES - Sets an environment variable called `ChocolateyBrandingLocation`. - .INPUTS - None - .OUTPUTS - None - #> - - $brandingLocation = $env:ChocolateyBrandingLocation - - if ($null -eq $brandingLocation) { - $chocoInstallLocation = $env:ChocolateyInstall - $brandingLocation = Join-Path -Path $chocoInstallLocation -ChildPath 'branding' - } - - # Add a drive letter if one doesn't exist - if (-not($brandingLocation -imatch "^\w:")) { - $brandingLocation = Join-Path $env:systemdrive $brandingLocation - } - - if (-not($env:ChocolateyBrandingLocation -eq $brandingLocation)) { - try { - Set-EnvironmentVariable -Name "ChocolateyBrandingLocation" -Value $brandingLocation -Scope User - } catch { - if (Test-ProcessAdminRights) { - # sometimes User scope may not exist (such as with core) - Set-EnvironmentVariable -Name "ChocolateyBrandingLocation" -Value $brandingLocation -Scope Machine - } else { - throw $_.Exception - } - } - } - - return $brandingLocation - } - -1. Run the command `choco pack` -1. Deploy the generated `chocolateygui-branding.nupkg` to the repository that you are using -1. Install the Chocolatey GUI Branding package \ No newline at end of file diff --git a/input/en-us/features/chocolatey-central-management.md b/input/en-us/features/chocolatey-central-management.md deleted file mode 100644 index 01af7e9ce0..0000000000 --- a/input/en-us/features/chocolatey-central-management.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -Order: 100 -xref: ccm -Title: Chocolatey Central Management (C4B) - Endpoint Management -Description: Centrally access information on all client machines in your environment -RedirectFrom: docs/features-chocolatey-central-management ---- - -Chocolatey Central Management (CCM) provides you insights across your desktop and endpoint environments. - -Once installed and configured, you can use CCM to: - -* Bring reporting to the organizational level -* Quickly see all software across the organization and see what needs attention immediately -* Create reports for tracking and auditing purposes -* Manage endpoints with deployments through groups and collections - -> :choco-info: **NOTE** -> -> The information on this page has been spread out to an entire section and multiple pages. Links still here are due to code pointing to these. Please follow the link below for the most up-to-date information on CCM. - -Please see [Chocolatey Central Management](xref:central-management). - -## Roadmap - -Please see [Chocolatey Central Management](xref:central-management#roadmap). - -## Setup - -Please see [Central Management Setup](xref:ccm-setup). - -## FQDN Usage - -Please see [Central Management Service Setup](xref:ccm-service#fqdn-usage). diff --git a/input/en-us/features/create-packages.md b/input/en-us/features/create-packages.md deleted file mode 100644 index a2f3ef9209..0000000000 --- a/input/en-us/features/create-packages.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -Order: 40 -xref: create-your-own-packages -Title: Create your own packages -Description: Information on how to create your own Chocolatey package ---- - -Out of the box, Chocolatey comes with the ability for you to create your own Chocolatey packages. At the heart of any Chocolatey package is [PowerShell](xref:packaging-for-the-masses) (the automation language for Windows), so anything that you can imagine can go into a Chocolatey Package. This means that you can create a package for: - -- Installers -- Binaries -- Zips -- Scripts -- Anything - -We have [comprehensive documentation](xref:package-creation) on how to get started creating your first package, but if you want to jump straight in, after [installing Chocolatey](xref:setup-choco), run the following command: - -```powershell -choco new mypackage -``` - -And Chocolatey will create a package, using its built in [templating system](xref:create-custom-package-templates), that also walks you through the process for finalizing your package. \ No newline at end of file diff --git a/input/en-us/features/extensions.md b/input/en-us/features/extensions.md deleted file mode 100644 index c919b2c3e9..0000000000 --- a/input/en-us/features/extensions.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -Order: 70 -xref: extensions -Title: Extend Chocolatey With PowerShell Modules (extensions) -Description: Create your own custom extensions -RedirectFrom: docs/how-to-create-extensions ---- - -For years Chocolatey has allowed you to extend Chocolatey with your own PowerShell modules and functions. These are known as extensions. - -## Overview - -Extensions allow you to package up PowerShell functions that you may reuse across packages as a package that other packages can use and depend on. This allows you to use those same functions as if they were part of Chocolatey itself. Chocolatey loads these PowerShell modules up as part of the regular module import load that it does for built-in PowerShell modules. - -### Why Would I Create an Extension? - -To reduce code in your Chocolatey automation scripts. Packaging up logic as functions into a PowerShell module that you can version independently, fix issues in, and enhance without needing to touch existing packages that you have is pretty powerful. - -## Creating a Chocolatey Extension - -When it comes to extensions, Chocolatey takes a conventional approach. You must create a package with the suffix ".extension" and have a extensions folder with at least one PowerShell module in it. - -The name of the package should be "extensionname.extension". The name of the package minus ".extension" will be the name of the extension that is installed. - -* To create an extension package, run `choco new name.extension` and then delete everything but the nuspec. -* Then create an extensions folder in the root of the package. -* In the extensions folder, create your PowerShell module. -* The important file you will need is a PSM1 (PowerShell Module) file that loads up and ensures functions are available. Have a look at [profile module](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/chocolateyProfile.psm1) and [chocolatey-core.extensions module](https://github.com/chocolatey-community/chocolatey-packages/blob/master/extensions/extensions.psm1). -* When those functions are loaded by Chocolatey, they will already be available when your scripts run so you won't need to load up the files again in your install scripts - the functions will already be available! - - -Here's an example: https://community.chocolatey.org/packages/chocolatey-core.extension. The source is at https://github.com/chocolatey-community/chocolatey-packages/tree/master/extensions - -Yes, it is really that easy. Enjoy! - -## Recommendations - -### Naming Your Extension - -Avoid "Chocolatey" as part of the name. Yes the example is named that, but this extension is owned by the Core Chocolatey team, so it makes sense for that to be the name. - -### PowerShell Modules - -* The recommendation is typically as few PowerShell modules as possible in an extension, just enough to represent what that extension does. Strive for one module per extension package, although that may not be realistic. -* The module should explicitly export the functions, aliases, and cmdlets that are wanted to be used in Chocolatey automation scripts. - -### Taking a Dependency on an Extension Package - -When taking a dependency on an extension package, it is recommended to take a minimum version dependency. If there is functionality that is enhanced in that extension, you should bump that dependency version. - -#### Minimum Version Depdendencies - -What does a minimum version depdency look like? - -~~~xml - - - -~~~ - -#### Avoid Version Ranges For Extensions - -Avoid version ranges when it comes to extensions as it can lock out fixes and enhancements in the future. - -~~~xml - - - - - - - -~~~ - -#### Avoid Exact Version Dependencies For Extensions at All Costs - -Try to never lock into an exact version dependency: - -~~~xml - - - - -~~~ - -This locks every other package into that singular version and does not allow for upgrades and fixes. - -#### Version-less Dependencies - -There is also the concept of versionless dependencies. - -~~~xml - - - -~~~ - -Folks typically have used these in the past. They are less bad, but it just means that any version will do. diff --git a/input/en-us/features/hook.md b/input/en-us/features/hook.md deleted file mode 100644 index 75176146e3..0000000000 --- a/input/en-us/features/hook.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -Order: 75 -xref: hooks -Title: Extend Chocolatey With PowerShell Scripts (Hooks) -Description: Run PowerShell before and after Package Automation Scripts ---- - -A feature is available in Chocolatey CLI v1.2.0, which allows you to extend a package's automation script(s) with additional PowerShell scripts, called hooks. - -## Overview - -Hooks allow you to run code before a package automation script like a `chocolateyInstall.ps1` runs, or after. They even work when automation scripts are not included in the package. Each script can selectively target a single package ID, or run for all packages. Then they can be distributed using `.hook` packages. - -## Creating Hook Scripts - -Hook scripts are PowerShell `.ps1` files, and are run in the same environment as package automation scripts run, so they have access to all the same environment variables and helpers. - -The conditions for when a hook is run is based on the filename of the hook. The filename format is `--.ps1`. The first section is for the timing of when the hook script runs. Filenames that start with `pre` run before the package automation script (e.g. the `chocolateyInstall.ps1`), while filenames that start with `post` are run afterwards. The second section of the filename determines which package automation script the hook is run before or after. The third section of the filename is either a string of the package ID for which the hook should be run, or the keyword `all` to specify that the hook should be run for all package IDs. - -If a package does not contain a `chocolateyInstall.ps1`, but a `pre-install-all.ps1` hook is installed, then that hook will still run at the same point in the package installation as the `chocolateyInstall.ps1` would have been run if the package had included it. - -## Creating Hook Packages - -Hooks can be installed just like extensions, via a specific package type, namely `.hook`. The name of the installed hook folder is the package `id`, minus the `.hook`. - -How to create a Hook package: - -1. Create a package with a `.hook` suffix like `choco new name.hook` -1. Delete the created files and folders except for the `.nuspec` -1. Create a `hook` folder in the root of the package (next to the `.nuspec`). -1. Put your hook PowerShell script files inside the `hook` folder. -1. Pack and install your new Hook package. - -## Global Hooks - -These files are run either before (pre) or after (post) the normal Chocolatey install/upgrade/uninstall operation, for all Chocolatey packages. - -Once a global hook is installed (either manually or via hook package), any subsequent Chocolatey operations (say for example the installation of another package), will make use of the newly installed (or available), hook scripts. - -## Package Specific Hooks - -You can also create a package-specific hook by following the naming convention `--.ps1` where `` is the `id` of the Chocolatey package you would wish to execute hooks against. - -The hooks will behave in the same way as global hooks, running either before (pre) or after (post) the normal Chocolatey install/upgrade/uninstall operation for only a Chocolatey package whose `id` matches the `id` in the hook script name. - -## Skipping Hooks - -Chocolatey provides away for skipping the running of hooks for a particular package. If you would like to skip hooks for the installation of a particular package, simply add the `--skip-hooks` option to the list of parameters you pass to the command. - -## Recommendations - -### Still under development - -Hook scripts and packages are still new, so guidelines and best practices are still being determined. Follow along at the [Chocolatey Community Hooks Repository](https://github.com/chocolatey-community/chocolatey-hooks) for the latest information. - -### Avoid taking dependencies on regular packages - -It is best to avoid having a `.hook` package taking a dependency on regular packages. This is so the included hooks from the package can be installed before other packages get initially installed. For example, if there is a `pre-install-git.ps1` hook and the `.hook` package it is included in takes a dependency on `git`, then the `chocolateyInstall.ps1` from the `git` package would have already run before the hook is installed, which is counterproductive. - -### Do take dependencies on extension packages - -If any hook script in a `.hook` package require helpers from an `.extension` package, then make sure that the `.hook` package takes a dependency on that `.extension` package. - -### Don't take dependencies on hook packages - -Don't add a hook package as a dependency for your regular package. Hook scripts are intended to be added only by the user of Chocolatey CLI. If your package requires functionality similar to that which would normally be provided via a hook script package, then it should be added directly to the standard automation scripts for the package. Adding a hook package as a dependency to your regular package will cause the package to fail validation on the Chocolatey Community Repository. - -### Don't add hook scripts to regular packages - -Don't add hook scripts to your regular Chocolatey package. If your package requires functionality similar to that which would normally be provided via a hook script package, then it should be added directly to the standard automation scripts for the package. Adding a hook script to your regular package will cause the package to fail validation on the Chocolatey Community Repository. \ No newline at end of file diff --git a/input/en-us/features/host-packages.md b/input/en-us/features/host-packages.md deleted file mode 100644 index f4473316d4..0000000000 --- a/input/en-us/features/host-packages.md +++ /dev/null @@ -1,383 +0,0 @@ ---- -Order: 50 -xref: host-packages -Title: Host packages internally -Description: How to host your own Chocolatey packages, rather than use the Chocolatey Community Repository -RedirectFrom: docs/how-to-host-feed ---- - -> :choco-info: **NOTE** -> -> Refer to [How To Set Up Chocolatey For Organizational/Internal Use](xref:organizational-deployment-guide) in tandem with this article. - -## Why? - -Chocolatey has had the ability to be able to work with packages from one or more sources since its inception back in 2011. With that, Chocolatey comes with a default package repository configured - the [community package repository](https://community.chocolatey.org/packages). However due to the community repository being publicly available and subject to distribution rights, it has a failure point in that it can not be 100% reliable (most packages can't contain software and must download at runtime). It's not something an organization hosting their own package repository would be subject to, so we recommend organizational use of Chocolatey should include an internal package repository. Organizations looking to use Chocolatey should review the following topics to learn more: - -* [Community package repository - organizational use](xref:community-packages-disclaimer) -* [Security and the community repository](xref:security#organizational-use-of-chocolatey) - -## Host your own server - -There are a few types of package repositories, [folder/unc share](#local-folder--unc-share), [simple server](#simple-server), the sophisticated [package gallery](#package-gallery), and the more sophisticated [commercial package repositories](#commercial-package-repositories). - -## Recommendations - -From the Chocolatey Software team, our current recommendations for organizational use are Artifactory, Nexus, or ProGet. All are quite robust, and two of those options can be used without cost. For more information, see [commercial package repositories](#commercial-package-repositories). - -### Known Hosting Options - -Some of these options also work from a non-Windows hosting perspective. See [Non-Windows Hosting](#non-windows-hosting). - -* File Share\UNC share (below) -* SCCM Distribution Points (when used as a file share) -* Sonatype Nexus - [Nexus2](https://books.sonatype.com/nexus-book/reference/nuget-nuget_hosted_repositories.html) / [Nexus3](https://books.sonatype.com/nexus-book/3.0/reference/nuget.html#nuget-hosted)- Sonatype Nexus has a built-in simple server -* [ProGet](http://inedo.com/proget/overview) - ProGet gives you a ready to go On-Premise option. Enterprise has replication -* [Artifactory Pro](https://www.jfrog.com/artifactory/) - see [Artifactory NuGet Repositories](http://www.jfrog.com/confluence/display/RTF/NuGet+Repositories) -* [MyGet](https://www.myget.org/) - MyGet offers public and private cloud-hosting options if you don't want to handle all of the pain of setup and administration. MyGet offers some stellar options like multi-feed aggregation, mirroring, and source package build services! -* [TeamCity](https://www.jetbrains.com/teamcity/) has built-in Simple Server -* NuGet.Server -* [NuGet Gallery](https://github.com/NuGet/NuGetGallery/wiki/Hosting-the-NuGet-Gallery-Locally-in-IIS) -* Chocolatey Gallery -* Visual Studio Team Services (use NuGet v2 urls) -* [Cloudsmith](https://cloudsmith.com) - Cloudsmith is a universal, cloud-native package management solution for Deployment or Distribution. All your packages, in any format, including Chocolatey, NuGet and Powershell, in one location and accessible across the organization. - -#### Others - -These are other known servers, but we don't know the quality or compatibility of these frameworks as they relate to Chocolatey packages. - -* [Express Chocolatey Server](https://www.npmjs.com/package/express-chocolatey-server) - Open source, OS-agnostic, read-only, does not require .NET or Windows, based on [Express](https://expressjs.com/) -* [Klondike](https://github.com/themotleyfool/Klondike) - Ember front-end that builds on NuGet.Lucene for private NuGet package hosting -* [PHP NuGet](http://www.kendar.org/?p=/dotnet/phpnuget) - Simple server built in PHP -* [LaGet](https://github.com/ikkentim/LaGet) - A NuGet server written using the Laravel PHP Framework -* [Hazel](https://github.com/MPIB/hazel) - Simple server built in Rust - -## Package Version Immutability - -A package version is immutable on some sources. This means that everybody's version 1.0.1 of a particular package is the same. You do not need to worry about this when updating with newer versions of packages, because each package version compiled nupkg has the unique version in the name (e.g `bob.1.0.0.nupkg` vs `bob.1.0.1.nupkg` ). - -Package immutability is usually desired, because then you know that everyone on v1.0.0 of a package has exactly the same code as does even everyone else. Even a broken version v1.0.0 gives you a global understanding that everyone who has v1.0.0 has exactly the same bits. This really simplifies administration. Without immutability, there is no guarantee that a version of a package installed is the same as the version of the package at the source. - -## Local Folder / UNC Share (CIFS) - -Perhaps the easiest to set up and recommended for testing quick and dirty scenarios, local folder is easily a strong point when you need a quick source for packages. - -### Advantages - -* Speed of setup (can be setup almost immediately). -* Package store is filesystem. -* Can be easily upgrade to Simple Server. -* Permissions are based on file system/share permissions. -* Can manage PowerShell gallery type packages. -* There is no limitation on package sizes (or rather, it can likely handle 100MB+ file sizes, maybe even GB sized packages). Don't create multiple GB sized packages, what is wrong with you?! ;) - -> :choco-info: **NOTE** -> -> If you must create large packages, see [Package Reducer](xref:package-reducer) for keeping used space down on client machines. - -### Disadvantages - -* Anyone with permission can push and overwrite packages. -* No HTTP/HTTPS pushing. Must be able to access the folder/share to push to it. -* Starts to affect choco performance once the source has over 500 packages (maybe?). -* No tracking on number of downloads / no package statistics -* **Big disadvantage**: For a file share there is not a guarantee of package version immutability. Does not do anything to keep from package versions being overwritten. This provides no immutability of a package version and no guarantee that a version of a package installed is the same as the version in the source. - -### Local Folder Share Setup - -No really, it's that easy. Just set your permissions appropriately and put packages in the folder (no subfolders). You are already done. Okay, two additional considerations: - -* [Folder Structure](#local-folder-or-share-structure) -* [Permissions](#local-folder-permissions) - -#### Local Folder Or Share Structure - -The structure should just be a flat folder or share (no subfolders) with nupkgs inside that folder. You get that when you choco push to that location. No subfolders, no `nuget add` type of setup will work for Chocolatey with those local folders and shares. - -> :choco-info: **NOTE** -> -> If you build a local NuGet folder repository using NuGet.exe v3.4+, where you use `nuget add`, you may find that it doesn't produce the results you might expect when you are using Chocolatey. It creates subfolders and adds those nupkgs in an optimized way for query. That is fine when there is a server like Chocolatey.Server that does that but has a way to translate that to an OData feed. When Chocolatey is querying those local folders and shares, it uses what is built into the Chocolatey client (choco.exe). That is currently a very enhanced version of NuGet v2, so it won't understand that optimized subfolder structure and you may get no results. So keep things simple and flat for those types of repositories. - -#### Local Folder Permissions - -Permissions can be interesting with a file share. If you are using machine accounts like LocalSystem, they may not have access to network resources. However there is a way to handle that in domain environments. You would need to grant access to machines or anonymous access to the share (Everyone Read is likely not enough). - -A great read on your options can be found at the following Stack Exchange links: - -* https://serverfault.com/q/135867/79259 -* https://serverfault.com/q/41130/79259 - -A way to do this with LocalSystem: - -1. Create a global group on the Domain - * add all machines to this group -1. Add this group to the share permissions with "Read" Access -1. Add this group to the NTFS permissions with "Read" Access - -> :choco-info: **NOTE** -> -> You'll need to add this group itself and not nest it inside of another one. - -## Simple Server - -There is where the bulk of NuGet OData compatible servers fall (NuGet.Server, Chocolatey.Server, etc). There are simple servers that are very enhanced, which fall into the [Commercial Package Repositories](#commercial-package-repositories) section. - -* Since Chocolatey just uses an enhanced version of the NuGet framework, it is compatible everywhere you can put a NuGet package. -* We recommend Chocolatey.Server if you are choosing between these options. -* A simple server typically has one repo per instance and manages only Chocolatey / NuGet packages. - -### Known Simple Server Options - -* NuGet.Server -* [TeamCity](https://www.jetbrains.com/teamcity/) has built-in Simple Server -* [Visual Studio Team Services (NuGet v2 endpoints)](https://docs.microsoft.com/en-us/vsts/package/overview) - [Setup](https://docs.microsoft.com/en-us/vsts/package/get-started-nuget) (Remove the part of the url that is /v3/index.json and use /v2 instead) - you may also need to [setup a personal access token](https://docs.microsoft.com/en-us/vsts/accounts/use-personal-access-tokens-to-authenticate). -* [NuGet.Java.Server](http://blog.jonnyzzz.name/2012/03/nuget-server-in-pure-java.html) ([NuGet Package](https://www.nuget.org/packages/NuGet.Java.Server)) - simple server (same tool used in TeamCity) -* [PHP NuGet](http://www.kendar.org/?p=/dotnet/phpnuget) -* [Hazel](https://github.com/MPIB/hazel) -* [LaGet](https://github.com/ikkentim/LaGet) -* [Klondike](https://github.com/themotleyfool/Klondike) -* Visual Studio Team Services (use NuGet v2 urls) - -If the option you've chosen is not listed, take a look at [known hosting options](#known-hosting-options) and follow the link from there to see what the vendor provides in the way of documentation. - -### Advantages - -* Setup can be really simple - just a website and IIS for some simple servers. -* Windows is not required - there are at least two pure Java versions (see [Non-Windows Hosting](#non-windows-hosting)). -* Push over HTTP / HTTPS/TLS. -* Authentication / Authorization: - * API key for pushing packages. - * Basic Authentication with IIS. -* No direct access to packages so security can be locked down to just modify through push. -* Package store is file system. -* Can manage PowerShell gallery type packages. - -### Disadvantages - -* May only have one API key per repository. -* Starts to affect performance once the source has over 2,000 packages for some sources. It depends on how they keep that information (in a db or file scans). -* Authentication is typically limited to Basic Auth. -* No moderation. -* May not have a website for viewing package information. Use ChocolateyGUI for seeing package information. -* No package statistics for most of the simple server sources. -* Package size may be limited to 28.61MB by default on some simple servers. Depending on your simple server - For IIS simple servers package size can be controlled through [maxAllowedContentLength](https://msdn.microsoft.com/en-us/library/ms689462(v=vs.90).aspx) and [maxRequestLength](https://msdn.microsoft.com/en-us/library/e1f13641(v=vs.100).aspx). For others like Nexus, it may already be set very high. You can host the installer internally somewhere and access it through packaging though. - -The actual limit for package sizes varies depending on what each simple server can handle (usually determined by the limitation of pushing a package to the server). If you determine what those are, we'd be happy to list each one here. - -#### Chocolatey.Server Setup - -Please see [Set up the Chocolatey.Server](xref:set-up-chocolatey-server). More details below on what this option provides. - -[Chocolatey Simple Server](https://community.chocolatey.org/packages/chocolatey.server) is a simple Nuget.Server that is ready to rock and roll. It has already completed Steps 1-3 of NuGet's [host your own remote feed](https://docs.nuget.org/Create/Hosting-Your-Own-NuGet-Feeds#creating-remote-feeds). Some things to consider with Chocolatey.Server as compared to other options: - -* Uses same enhanced NuGet that Chocolatey uses so you can see more information in search if you choose to use those things. -* Allows packages up to 2GB. Package size can be controlled through [maxAllowedContentLength](https://msdn.microsoft.com/en-us/library/ms689462(v=vs.90).aspx) and [maxRequestLength](https://msdn.microsoft.com/en-us/library/e1f13641(v=vs.100).aspx). - -> :choco-info: **NOTE** -> -> Commercial options of Chocolatey also may have support for the Chocolatey.Server. - -#### NuGet.Server Setup - -Setting up NuGet.Server is very much a hands on approach for a packaging server - it requires Visual Studio as you will be adding the NuGet package to a Website project. We recommend looking at Chocolatey.Server as it is nearly the same thing but fully ready to go (and with Chocolatey enhancements). - -Many google searches will throw out good ways to set up your own feed (hint: search for "host your own NuGet server feed") -Some notable references: - -* Nuget Docs [Host Your Own Remote Feed](https://docs.nuget.org/Create/Hosting-Your-Own-NuGet-Feeds#creating-remote-feeds) -* itToby - [Setup Your Own Chocolatey/NuGet Repository](http://blog.ittoby.com/2014/07/setup-your-own-chocoloateynuget.html) -* Rich Hopkins - [Bake your own Chocolatey NuGet repository](https://souladin.wordpress.com/2014/12/05/bake-your-own-chocolatey-nuget-repository/) -* Brandon - [Host NuGet Server in Azure](http://netitude.bc3tech.net/2015/01/07/create-your-own-hosted-nuget-server-in-azure/) - -## Package Gallery - -This is like what https://community.chocolatey.org (the community feed runs on). It is the most advanced, having both a file store for packages and a database for tracking all sorts of information. - -### Advantages - -* Can deal with thousands of packages with no performance issues. -* Package versions are immutable - in other words you can guarantee the version installed is the same as the version in the source. -* Package store can be File system, Azure blobs, or AWS S3 (**S3 available with Chocolatey Package Gallery only**). -* Multiple users each having their own API keys. -* User registration with email confirmation. -* Interaction and collaboration based. -* Can have administrators. -* Can take advantage of moderation (**Chocolatey Package Gallery only**). -* Package statistics (download counts, etc). -* A website to view package information. -* Can be configured to send email. -* Can manage PowerShell gallery type packages. - -### Disadvantages - -* Speed of setup (can take longer than the rest). There are many moving parts to configure. -* Requires Windows/IIS/SQL Server/SMTP (hopefully with the proper licenses on each of those). -* Not well-documented, could require some diligence to get working. -* A package should not be bigger than 150MB. You can host the installer internally somewhere and access it through packaging though. Package size can be controlled through [maxAllowedContentLength](https://msdn.microsoft.com/en-us/library/ms689462(v=vs.90).aspx) and [maxRequestLength](https://msdn.microsoft.com/en-us/library/e1f13641(v=vs.100).aspx). - -#### Package Gallery Setup - -Only approach this if you are a Windows Admin with significant experience in setting up SQL Server databases and IIS for ASP.NET MVC sites. We don't have resources to help support the setup, but we can point you to [NuGet Gallery Setup](https://github.com/NuGet/NuGetGallery/wiki/Hosting-the-NuGet-Gallery-Locally-in-IIS). - -##### Chocolatey Package Gallery Setup - -At this time we don't have setup instructions and are not keen to answer questions specifically surrounding the setup of a Chocolatey Gallery (the code behind chocolatey.org). This is due to specific necessary settings regarding the community packages repository and tight integration to what it offers. Chocolatey for Business is likely to offer a gallery at some point, depending on prioritization. - -## Commercial Package Repositories - -These are simple servers that have more advanced options and authentication scenarios, plus multiple repository types. This section accounts for the following types. - -### Commercial Options - -* [Artifactory Pro](http://www.jfrog.com/confluence/display/RTF/NuGet+Repositories) -* [Cloudsmith](https://cloudsmith.com/nuget-feed/) ([Chocolatey Documentation](https://help.cloudsmith.io/docs/chocolatey-repository), [NuGet Documentation](https://help.cloudsmith.io/docs/nuget-feed)) -* [Feedz.io](https://feedz.io/docs/package-types/chocolatey) -* [Nexus2](https://books.sonatype.com/nexus-book/reference/nuget-nuget_hosted_repositories.html) / [Nexus3](https://books.sonatype.com/nexus-book/3.0/reference/nuget.html#nuget-hosted) -* [MyGet](https://www.myget.org/) -* [ProGet](http://inedo.com/support/documentation/proget/installation/installation-guide) - -If the option you've chosen is not listed, take a look at [known hosting options](#known-hosting-options) and follow the link from there to see what the vendor provides in the way of documentation. - -### Advantages - -* Setup can be really simple - just a website, IIS, and a local database or file to store configuration. -* May have free tier available (Artifactory is the only known option that does not have a free tier). -* Windows is not required for Nexus, Artifactory, or Cloudsmith. -* Push over HTTP / HTTPS/TLS. -* API key for pushing packages. -* No direct access to packages so security can be locked down to just modify through push or upload. -* Authentication / Authorization: - * Multiple api keys. - * Basic Authentication through IIS. - * RBAC (role-based access control) available in some options. - * LDAP authentication in some options (although Nuget/Chocolatey may not support this for package operations). -* Package stores can be file system, database, Azure blobs, and AWS S3 depending on the product. -* Website interface. - * Uploading packages can also be done through website. -* Multiple repositories in an instance. -* Multiple repository types (not limited to just NuGet/Chocolatey types). -* HA (High Availability) available in some options. -* Replication available in some options. -* Can manage PowerShell gallery type packages. - -### Disadvantages - -* Still unlikely to have moderation. You may not want this anyway. -* Package size may be limited. Check with the vendor to learn what their limits are. You can host the installer internally somewhere and access it through packaging though. Many times these repository types will also support a binary/raw repository you can use to download installers from, keeping a single point of failure on the package repository server. - -The actual limit for package sizes varies depending on what each server can handle (usually determined by the limitation of pushing a package to the server). If you determine what those are, we'd be happy to list each one here. - -### Commercial Repository Setup - -Most hosting options have great information on how to set up the package repository. Please see the documentation with each vendor to learn what options are available and how to set up. - -### Commercial Repository System Requirements - -For commercial options, we've compiled a list of recommended needs for your server repositories. For Chocolatey clients, please see [client requirements](xref:organizational-deployment-guide). What you will see below are not the minimum values, you can typically get that at each of the links. These are what we typically recommend for use with Chocolatey. All of these options support High Availability (HA) options as well, so if you need something like that for a geographically diverse enterprise, there are options to meet those needs. Keep in mind pricing of each of these goes up based on your needs. - -#### Artifactory Pro - -* Windows or Linux Server -* CPU - 8-16 cores -* RAM - 16GB+ RAM (12GB of RAM reserved specifically for JVM heap) -* Storage (HDD) - At least 2-5TB of free space for a local file store of artifacts (you need 3 times the size of artifacts you will store). -* Chocolatey Repository Type: NuGet - -See https://www.jfrog.com/confluence/display/RTF/System+Requirements for more details. - -**PRICING**: Starts at $2,950/year (for Artifactory Pro). No free option for Chocolatey/NuGet type packages - https://jfrog.com/pricing/. - -#### Artifactory Enterprise with High Availability - -* Artifactory Cluster Server (Each): Windows or Linux Server with 8-16 cores (CPU), 16GB+ RAM (12GB of RAM reserved specifically for JVM heap), and probably at least 100GB of free space (as the artifacts are stored over on the NFS). This is similar to Artifactory Pro section above. -* Network: High Speed LAN (all Artifactory Servers must be on same LAN for syncing purposes). -* Shared Storage: NFS, AWS S3, Google Cloud Storage, or Local File System - Recommend NFS with 3 times the total size of what you will store (and a backup SAN) - 2-5TB+ space. -* Database: You must use an external database (one between all nodes), and it must be VERY powerful. Pretty much the highest specs you can configure on a Windows machine if you use SQL Server. It must support the max number of connections possible from all Artifactory cluster nodes in your system. 16+ cores (CPU), 64GB+ RAM, 5TB+, etc -* Load Balancer: Assume powerful - this will be software-based (such as nginx or HAProxy) or an appliance (such as F5 or Citrix). -* May or may not support cross-datacenter replication. - -See https://www.jfrog.com/confluence/display/RTF/Artifactory+High+Availability for more details. - -**PRICING**: Starts at $29,500/year (for Artifactory Enterprise) - https://jfrog.com/pricing/. - -#### Sonatype Nexus Repository Manager 2 - -* Windows, Mac OSX, or Linux Server -* CPU - 2-4 cores (Recommend 4+) -* RAM - 16GB+ (4GB of RAM reserved specifically for JRE) -* Storage (HDD) - At least 2-5TB of free space for a local file store of artifacts. [How much space do you need?](https://blog.sonatype.com/2012/01/sizing-nexus-how-much-space-do-you-need/) -* Chocolatey Repository Type: NuGet - -See https://help.sonatype.com/repomanager2/system-requirements for more details. - -**PRICING**: Starts at free (for Sonatype Nexus Repository Manager) - https://www.sonatype.com/nexus-product-pricing. - -#### Sonatype Nexus Repository Manager 3 - -* Windows, Mac OSX, or Linux Server -* CPU - 4 cores (Recommend more) -* RAM - 16GB+ (4GB of RAM reserved specifically for JRE) -* Storage (HDD) - At least 2-5TB of free space for a local file store of artifacts. [How much space do you need?](https://blog.sonatype.com/2012/01/sizing-nexus-how-much-space-do-you-need/) -* Chocolatey Repository Type: NuGet - -See https://help.sonatype.com/repomanager3/installation/system-requirements for more details. - -**PRICING**: Starts at free (for Sonatype Nexus Repository Manager) - https://www.sonatype.com/nexus-product-pricing. - -#### Sonatype Nexus Repository Manager 3 High Availability - -* 3 Node Cluster of Nexus Repository Manager Pro (NXRM Pro) instances (see Nexus 3 above for requirements). -* Network: High Speed LAN (all NXRM Pro Servers must be on same LAN for syncing purposes). -* Shared Storage: Appliance-based (such as NAS), or software-based (such as SMB). This will be shared across all Servers, so they will need to be able to read and write to it at high speed. Recommend appliance-based (NAS) with 3 times the total size of what you will store (and a backup) - 2-5TB+ space. -* Load Balancer: Assume powerful - this will be software-based (such as nginx or HAProxy) or an appliance (such as F5 or Citrix). -* Does not support cross-datacenter replication - only supports single datacenter. - -See https://help.sonatype.com/repomanager3/high-availability for details. It is very light on requirements, so assume similar to Artifactory's HA setup, minus a need for an external database. - -**PRICING**: Please see https://www.sonatype.com/nexus-product-pricing and contact Sonatype as it is not clear. You need at least 3 NXRM (Nexus Repository Manager) Pro licenses. There may be additional costs. - -#### ProGet - -* Windows Server or Linux (Docker) -* CPU - 2 to 4 cores -* RAM - 4GB to 8GB -* Storage (HDD) - we recommend 2-5TB of free space for a local file store of artifacts (ProGet itself requires less than 100MB free space) -* Database: SQL Server (built-in SQL Express is fine, or use your existing SQL Server) -* Chocolatey Repository Type: Chocolatey or NuGet - -See https://inedo.com/support/documentation/proget/installation/installation-guide for more details. - -**PRICING**: Starts at free (for ProGet) - https://inedo.com/proget/pricing. - -#### ProGet Enterprise High Availabilty - -* Windows Server Cluster or Kubernetes Cluster, each with similar specifications as above; note that artifacts are stored on shared storage -* Shared Storage: Appliance-based (such as NAS), or software-based (such as SMB). This will be shared across all Servers, so they will need to be able to read and write to it at high speed. Recommend appliance-based (NAS) with 3 times the total size of what you will store (and a backup) - 2-5TB+ space. -* Database: SQL Server with Database Clustering Recommended; high specs are not a requirement -* Load Balancer: Assume powerful - this will be software-based (such as nginx or HAProxy) or an appliance (such as F5 or Citrix). -* Supports cross-datacenter replication with multiple instances - -See https://inedo.com/support/documentation/proget/administration/high-availability for details. - -**PRICING**: Starts at $9,995 (for ProGet Enterprise) - https://inedo.com/proget/pricing. - -#### Cloudsmith - -* Cloudsmith is a universal, cloud native package management solution. It is cloud hosted so no infrastructure requirements are required. -* Chocolatey Repository Type: NuGet https://help.cloudsmith.io/docs/chocolatey-repository - -**PRICING**: A range of tiers are available, to suit all sizes of teams, for internal and external distribution, public and private - https://cloudsmith.com/product/pricing/. - -## Non-Windows Hosting - -If you don't want to host on Windows you have only the following options (from least advanced to most advanced - these options typically also work on Windows): - -* CIFS share -* [Express Chocolatey Server](https://www.npmjs.com/package/express-chocolatey-server) - Open source, OS-agnostic, read-only, does not require .NET or Windows, based on [Express](https://expressjs.com/) -* [NuGet.Java.Server](http://blog.jonnyzzz.name/2012/03/nuget-server-in-pure-java.html) ([NuGet Package](https://www.nuget.org/packages/NuGet.Java.Server)) - simple server (same tool used in TeamCity) -* [TeamCity](https://www.jetbrains.com/teamcity/) - contains built-in simple server -* [PHP NuGet](http://www.kendar.org/?p=/dotnet/phpnuget) - Simple server built in PHP -* [Hazel](https://github.com/MPIB/hazel) - Simple server built in Rust -* [Cloudsmith](https://cloudsmith.com) - see [Cloudsmith NuGet Repositories](https://help.cloudsmith.io/docs/nuget-feed) -* [Artifactory Pro](https://www.jfrog.com/artifactory/) - see [Artifactory NuGet Repositories](http://www.jfrog.com/confluence/display/RTF/NuGet+Repositories) -* [Sonatype Nexus](https://books.sonatype.com/nexus-book/reference/nuget-nuget_hosted_repositories.html) diff --git a/input/en-us/features/index.md b/input/en-us/features/index.md deleted file mode 100644 index 59343d92eb..0000000000 --- a/input/en-us/features/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -Order: 30 -xref: features -Title: Features -Description: Information about the different features that Chocolatey has ---- \ No newline at end of file diff --git a/input/en-us/features/install-directory-override.md b/input/en-us/features/install-directory-override.md deleted file mode 100644 index c715d6fdf0..0000000000 --- a/input/en-us/features/install-directory-override.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -Order: 180 -xref: install-directory-override -Title: Ubiquitous Install Directory Option (Pro+) -Description: Override the install directory for native installers -RedirectFrom: docs/features-install-directory-override ---- - -The ubiquitous install directory switch for [customers](https://chocolatey.org/pricing)! The only switch you will ever need for overriding the install directory for native installers! When working with packages that use native installers (software that actually installs on a machine), Chocolatey is able to override the default installation directory from a simple switch you pass to choco. - -It can be a pain determining the native installer type (MSI, NSIS, InnoSetup, etc) for a piece of software and then determining what the install directory argument should look like. While you [can change the installation directory without this switch even in Chocolatey open source](xref:getting-started#overriding-default-install-directory), you will see that the ubiquitous switch makes it very easy and a low amount of work on your part. - -With the ubiquitous switch, you are not only saving time, but also possible errors in passing the wrong arguments to an installer! - -## Usage - -Just pass `--install-directory=value` along and Chocolatey will determine what the actual call to the native installer needs to be and manage that for you! - -![choco install 1password --install-directory c:\1password](/assets/images/chocopro_features_installdirectory.png) - -![Install override - if you are on https://docs.chocolatey.org/en-us/features/install-directory-override, see commented html below for detailed description of image](/assets/images/features/features_override_install_directory.png) - - - -## See It In Action - -![Directory override in action](/assets/images/gifs/chocopro_features_installdirectory.gif) - -> :choco-info: **NOTE** -> -> To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b. - -## Options and Switches - -The following options are added to install and upgrade commands. - -~~~sh - --dir, --directory, --installdir, --installdirectory, --install-dir, - --install-directory=VALUE - Install Directory Override - Override the default installation - directory. Chocolatey will automatically determine the type of - installer and pass the appropriate arguments to override the install - directory. The package must use Chocolatey install helpers and be - installing an installer for software. Licensed versions only. -~~~ - -## FAQ - -### How do I take advantage of this feature? - -You must have a [licensed edition of Chocolatey](https://chocolatey.org/pricing) (Pro and/or Business). Pro is a personal, named license that costs about the price of a lunch outing per month and comes with several other features. Business editions are great for organizations that need more business friendly features from their software management tool. - -### I'm a licensed customer, now what? - -You just create a package or find a package you want to install that uses a native installer (ends up in Programs and Features). - -### How does it work? - -Chocolatey is able to inspect the installer file to learn what it is and can do this for almost 15 different types of installers (there are over 20)! Once it understands what type of file it is, it knows how to install/upgrade/uninstall that piece of software. - -The recommended calls for installing native installers are to use `Install-ChocolateyPackage` (or `Install-ChocolateyInstallPackage`). This allows Chocolatey to override that directory automagically. - -### Do you have plans to make this work for zip files? - -We do have plans to extend this to archive packages as well. diff --git a/input/en-us/features/integrations.md b/input/en-us/features/integrations.md deleted file mode 100644 index 96d5b0e4db..0000000000 --- a/input/en-us/features/integrations.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -Order: 60 -xref: integrations -Title: Integrates with everything -Description: Information on how Chocolatey can integrate with almost every tool -RedirectFrom: docs/features-infrastructure-automation ---- - -Chocolatey integrates with several infrastructure automation tools! - -With most of these tools, the interface you would interact with Chocolatey would be through the tool or through the interfaces of the tool, like in scripts. - -## Summary - -### Chocolatey Integration Implementation with Common Configuration Managers - - - -## Ansible - -Ansible has the `win_chocolatey` module that manages both packages and the installation of Chocolatey itself. - -```yaml -win_chocolatey: - name: git - source: https://my.internal.repository/api/v2/ -``` - -[Read More...](https://docs.ansible.com/ansible/latest/collections/chocolatey/chocolatey/win_chocolatey_source_module.html) - -## Boxstarter - -Boxstarter is a lightweight configuration management utility. - -> Repeatable, **reboot resilient** Windows environment installations made easy using Chocolatey packages. When its time to repave either **bare metal or virtualized instances**, locally or on a **remote machine**, Boxstarter can automate both trivial and highly complex installations. Compatible with all Windows versions from **Windows 7/2008 R2 forward**. - -[Read more...](http://boxstarter.org/) - -## Chef - -Chef 12.7+ has a [built-in](https://www.chef.io/blog/2016/02/12/chef-client-12-7-released/) `chocolatey_package` resource to use with Chocolatey. - -```ruby -chocolatey_package 'git' do - action :install - source 'https://my.internal.repository/api/v2' -end -``` - -[Resource - Read More...](https://docs.chef.io/resource_chocolatey_package.html) - -When you need to also install Chocolatey, you would use the community cookbook to do so. The cookbook is maintained by the Chocolatey team. It has a package resource that can be used with older Chef versions. - -```ruby -include_recipe 'chocolatey' -``` - -[Cookbook - Read More...](https://supermarket.chef.io/cookbooks/chocolatey/) - -### Example - -Here's a more in depth example from [Nordstrom](https://github.com/Nordstrom/chefdk_bootstrap/blob/master/recipes/windows.rb): - -```ruby -include_recipe 'chocolatey' - -home = Dir.home -%W( - #{home}/.chef - #{home}/chef - #{home}/chef/cookbooks -).each do |directory| - directory directory -end - -packages = node['chefdk_bootstrap']['package'] - -packages.each do |pkg, install| - include_recipe "#{cookbook_name}::#{pkg}" if install -end -``` - -Another example from [Facebook](https://github.com/facebook/IT-CPE/tree/master/chef/cookbooks/cpe_choco): - -```ruby -node.default['cpe_choco']['sources']['bacon'] = - 'source' => 'http://bacon.es.yummy', -} -``` - -## Octopus Deploy - -Octopus is a friendly deployment automation tool for .NET developers. It integrates with lots of utilities, and they have a template for installing Chocolatey packages: https://library.octopusdeploy.com/step-template/actiontemplate-chocolatey-install-package - -[Read more...](https://octopus.com/) - -## Otter - -Otter has an [open source Chocolatey extension](https://github.com/Inedo/inedox-chocolatey) that allows installing and uninstalling packages, specifying package versions, chocolatey sources, chocolatey features, and installing chocolatey itself. - -Otter also keeps an inventory of Chocolatey packages installed on any or all servers. - -```otter -Chocolatey::Ensure-Package -( - Name: 7zip.install, - Version: 18.5, - Source: https://proget.local/chocolatey -); - -Chocolatey::Ensure-Installed -( - Version: latest, - Source: https://proget.local/chocolatey -); - -Chocolatey::Ensure-Source -( - Name: Internal, - Url: https://proget.local/chocolatey, - Credential: DomainCred -); - -Chocolatey::Ensure-Feature -( - Feature: checksumFiles, - Enabled: false -); -``` - -[Read More...](https://inedo.com/den/otter/chocolatey) - -## PowerShell DSC - -PowerShell DSC (Desired State Configuration) has a cChoco module that can manage both packages and the installation of Chocolatey itself. - -```powershell - cChocoInstaller installChoco - { - InstallDir = "c:\ProgramData\chocolatey" - } - - cChocoPackageInstaller installGit - { - Name = "git" - DependsOn = "[cChocoInstaller]installChoco" - } -``` - -[Read More...](http://www.powershellgallery.com/packages/cChoco/) - -## PowerShell PackageManagement - -> :choco-info: **NOTE** -> -> Chocolatey has a prototype provider for the built-in package manager on Windows 10/Windows Server 2016 that was created by Microsoft awhile back. It is not fully functional and it may have security issues. If you want to use Chocolatey with PackageManagement, we recommend using ChocolateyGet, which is a nice bridge until an official one is implemented. No ETA has been defined. - -[PowerShell PackageManagement (aka OneGet)](https://github.com/OneGet/oneget) is a package manager **aggregator** that depends on the existence of package managers as providers to work, one of which is Chocolatey. - -## PSDeploy - -PSDeploy is a quick and dirty module to simplify PowerShell based deployments. - -```powershell -Deploy SingleChocolateyPackage { - By Chocolatey { - FromSource 'c:\ChocolateyPackages\examplepackage.0.1.1.nupkg' - To "http://your-choco-repo.internal.com/" - WithOptions @{ - ApiKey = 'yourAPIkey' - Force = $true - } - } -} -``` - -[Read More...](http://psdeploy.readthedocs.io/en/latest/Example-Chocolatey-Deployment/) - -## Puppet - -Puppet has a [Supported module](https://forge.puppet.com/supported) for Chocolatey `puppetlabs/chocolatey`. Note that there is also a `chocolatey/chocolatey` module, the supported module is a drop in replacement for the `chocolatey/chocolatey` module - please use `puppetlabs/chocolatey` as it has full configuration of Chocolatey. - -```puppet -include chocolatey - -package { 'git': - ensure => latest, - provider => 'chocolatey', - source => 'https://my.internal.repository/api/v2', -} -``` - -Puppet has some great documentation on getting started with Chocolatey. Be sure to check that out at [Create, Install, and Repackage with Chocolatey](https://puppet.com/docs/pe/2021.7/managing_windows_nodes.html#create_install_repackage_with_chocolatey). - -The Chocolatey team is most familiar with Puppet and has written some documentation for using Puppet with Chocolatey. Please see - -* [Install with Puppet](https://chocolatey.org/install#install-with-puppet) -* [Chocolatey Licensed Editions Configuration/Setup with Puppet](xref:setup-licensed#set-up-licensed-edition-with-puppet) - -> :choco-info: **NOTE** -> -> If anyone would be interested in providing documentation similar to the above for other frameworks, we'd accept it as Pull Requests at https://github.com/chocolatey/docs. - -[Read More...](https://forge.puppet.com/puppetlabs/chocolatey) - -## Saltstack - -Salt has a Chocolatey module that manages both packages and the installation of Chocolatey itself. - -```python -salt '*' chocolatey.bootstrap -salt '*' chocolatey.install git -``` - -[Read More...](https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.chocolatey.html) - -## System Center Configuration Manager - -Chocolatey integrates with SCCM by handling the software management, and pointing to [distribution points](https://docs.microsoft.com/en-us/mem/configmgr/core/servers/deploy/configure/install-and-configure-distribution-points) as the source for packages. This allows folks to get packages and larger binaries out to their network without constraints and still take advantage of Chocolatey's fantastic abilities! - -To direct Chocolatey package installs, you can still write GPOs to ensure this. - -## Microsoft Intune - -Chocolatey's Intune Integration is only available to our Chocolatey for Business customers. It allows you to take any Chocolatey package and convert them into an `.intunewin` format for pushing to your Intune tenant for hosting and distribution. - -To get started with the Chocolatey Intune Integration please reference our [setup and use documentation](https://docs.chocolatey.org/en-us/licensed-extension/intune/). diff --git a/input/en-us/features/made-for-automation.md b/input/en-us/features/made-for-automation.md deleted file mode 100644 index 39500188ad..0000000000 --- a/input/en-us/features/made-for-automation.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -Order: 10 -xref: made-for-automation -Title: Made for Automation -Description: Chocolatey is built with automation in mind, and can integrate into any workflow -ShowInNavBar: false -ShowInSideBar: false ---- - -> :choco-warning: **WARNING** -> -> This is a Work in Progress. Please check back later. \ No newline at end of file diff --git a/input/en-us/features/package-anything.md b/input/en-us/features/package-anything.md deleted file mode 100644 index 31a371a8c3..0000000000 --- a/input/en-us/features/package-anything.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -Order: 30 -xref: package-anything -Title: Package anything -Description: With Chocolatey you can package up anything, whether it is installers, application, zip, scripts, etc ---- - -Chocolatey brings with it the concept of a Universal Packaging format for Windows. At the heart of this is [PowerShell](xref:packaging-for-the-masses), the automation language for Windows. - -Since on a Windows machine you can pretty much do "anything" with PowerShell, you can pretty much do "anything" within a Chocolatey package. If you need to - -- install an msi or an exe -- deploy a standalone binary -- unzip an archive file -- place some scripts into a particular folder - -Then you can do all of these with Chocolatey. The benefit comes that you will then know exactly what version of these artifacts are deployed onto any machine, and as a result, you will know when some of these artifacts need to be updated. Gone are the days of guessing at what version of a binary is deployed onto any given machine. - -When you couple this with the knowledge that a single Chocolatey package can take a dependency on another Chocolatey package, then you can quite quickly see how simple it can be to chain together a complex installation scenario. For example, let's imagine that you want to install the [`vscode` package](https://community.chocolatey.org/packages/vscode), but you also wanted to perform some custom configuration after the installation was performed. You could create a separate package called `vscode-config`, which takes a dependency on `vscode`, and in that package, you could perform all the necessary configuration that you wanted to achieve. Then, when you run: - -```powershell -choco install vscode-config -``` - -Chocolatey will first ensure that all dependencies for this package are met, and will install the `vscode` package. Once complete, the installation of the `vscode-config` package will happen, and your custom configuration will be applied. The beauty of this approach is separation of concerns that can be achieved. Here the installation of `vscode` is completed as a single unit of work, and then the custom configuration is applied afterward. - -On top of this, Chocolatey has the concept of [extension packages](xref:extensions), which means that you can encapsulate common operations into a single Chocolatey package, which can then be used as a dependency on any other package that needs that functionality. This makes it incredibly simple to consolidate re-usable scripts into a versioned package, that can be used across multiple computers, and packages. A prime example of this is the [`chocolatey-core.extension`](https://community.chocolatey.org/packages/chocolatey-core.extension) package which was created by the Chocolatey Community to provide additional functionality on top of the core functions of Chocolatey itself. \ No newline at end of file diff --git a/input/en-us/features/package-audit.md b/input/en-us/features/package-audit.md deleted file mode 100644 index 462d268c5b..0000000000 --- a/input/en-us/features/package-audit.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -Order: 130 -xref: package-audit -Title: Package Audit (C4B) -Description: Know who installed what package and when -RedirectFrom: docs/features-package-audit ---- - -> Know who installed what package and when. - -Reporting is very important, and auditing not only when your installations occurred but who installed them can be critical. There is nothing that presents this kind of information as easily as you will be able to gather it with Chocolatey for Business (C4B) and Package Audit. - -## Usage - -When calling `choco list` (`choco list -lo` in Chocolatey CLI v1.x), add `--audit` to see information on who installed and when. - -### Requirements - -* Chocolatey (`chocolatey` package) v0.10.7+. -* Chocolatey for Business (C4B) Edition. -* Chocolatey Licensed Extension (`chocolatey.extension` package) v1.12.0+. - -## See It In Action - -> :choco-note: **NOTE** -> -> Packages installed prior to installation of Chocolatey Licensed Extension will only mention Id and Version of each package. - -
    -
  • - -
    • -
  • - -
    • -
- -::::{.tab-content .text-bg-body-secondary .p-3 .mb-3 .border-start .border-end .border-bottom .rounded-bottom} -:::{.tab-pane .fade .show .active #choco-v2-image role=tabpanel aria-labelledby=choco-v2-image-tab} - -![Package Audit - if you are on https://docs.chocolatey.org/en-us/features/package-audit, see commented html below for detailed description of image](/assets/images/features/features_package_audit_v2.png) - -::: -:::{.tab-pane .fade #choco-v1-image role=tabpanel aria-labelledby=choco-v1-image-tab} - -![Package Audit - if you are on https://docs.chocolatey.org/en-us/features/package-audit, see commented html below for detailed description of image](/assets/images/features/features_package_audit.png) - -::: -:::: - -When shown, the user and domain are for the user who actually performed the installation. The "Original User" is the user who requested the install (outside of [Self-Service](xref:self-service-anywhere), it would be the same as the installing user). The Installation Date and Time are in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC time. - - - -> :choco-info: **NOTE** -> -> To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b. - -## Options and Switches - -
    -
  • - -
    • -
  • - -
    • -
- -::::{.tab-content .text-bg-body-secondary .p-3 .mb-3 .border-start .border-end .border-bottom .rounded-bottom} -:::{.tab-pane .fade .show .active #choco-v2-options role=tabpanel aria-labelledby=choco-v2-options-tab} - -When calling `choco list`: - -~~~sh - --audit, --showaudit, --show-audit, --show-audit-info - Show Audit Information - Display auditing information for a package. - Available in business editions only. -~~~ - -::: -:::{.tab-pane .fade #choco-v1-options role=tabpanel aria-labelledby=choco-v1-options-tab} - -When calling `choco list -lo`: - -~~~sh - --audit, --showaudit, --show-audit, --show-audit-info - Show Audit Information - Display auditing information for a package. - Available in business editions only. -~~~ - -::: -:::: - -## FAQ - -### How do I take advantage of this feature? - -You must have a [Business edition of Chocolatey](https://chocolatey.org/compare). Business editions are great for organizations that need to manage the total software management lifecycle. - -### I'm a licensed customer, now what? - -Once you have Chocolatey for Business properly set up, any installations or upgrades performed will be automatically audited. All existing installs will not have audit information, so we recommend the first thing you install after Chocolatey is chocolatey.extension v1.12.0+. - -### How does it work? - -It just works. When you install/upgrade packages, the auditing information is automatically tracked. To see the information, you simply call `choco list --audit` (`choco list -lo --audit` in Chocolatey CLI v1.x) and if you want to see it in machine parseable format, add `-r` to the end of the command. - -### I only see the audit information on packages I've installed updated since switching over to C4B. - -This is expected. You need Chocolatey Licensed Extension v1.12.0+ installed and configured prior to installing/upgrading apps. - -### What is the difference between user and original user? - -User is the user that performed the installation/upgrade. When using the self-service feature, original user will be the original user who requested the install/upgrade. diff --git a/input/en-us/features/package-builder.md b/input/en-us/features/package-builder.md deleted file mode 100644 index 11dac7ffb2..0000000000 --- a/input/en-us/features/package-builder.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -Order: 120 -xref: package-builder -Title: Package Builder (C4B) -Description: Create fully ready to go software deployments for Windows in 5-10 seconds -RedirectFrom: docs/features-create-packages-from-installers ---- - -> Chocolatey's Package Builder allows you to create fully ready to go software deployments for Windows in 5-10 seconds! There is nothing faster than Chocolatey when it comes to preparing software for an unattended deployment across your organization. - -* Generate packages based on installers and zips -* Generate packages by reflecting over Programs and Features -* Generate packages from the Package Builder UI - -Creating packages is a pretty quick process as compared to manually installing software on multiple machines. There is still some time involved to create a package. Even the best packagers take between 5-10 minutes to create a package. Chocolatey's Package Builder creates high quality packages in 5-10 seconds when pointed to native installers and zips! You can even point package builder to both a 32-bit and 64-bit url and seconds later you have a fully functioning package using all local/embedded resources! - -Chocolatey for Business is able to inspect an installer and determine silent arguments and complete packaging components for you, saving you hours of time in packaging and maintaining software! - -## Usage - -### Command Line - -When calling `choco new`, just add `--file=value` to point to a native installer and Chocolatey for Business will automatically determine the silent arguments, create the packaging and wrap that all around the installer. - -![Create Packages from Installers - if you are on https://docs.chocolatey.org/en-us/features/package-builder, see commented html below for detailed description of image](/assets/images/features/features_packages_from_installers.png) - - - -### Package Builder UI - -Starting in version 1.8.0 of the licensed editions, you have access to the Package Builder UI. - -Simply right click on an installer, executable, or zip type and select "Create Chocolatey Package..." - -![Package Builder UI](/assets/images/package-builder/package-builder-ui.png) - -Then just add in and fill out the requested information. It uses `choco new` under the covers allowing you to really ramp up fast, especially when you don't have a lot of command line experience. - -Another way to bring up the ui is to call `packagebuilder` from the command line. - -## See It In Action - -### Package Builder CLI and Scripts - -We've prepared a short video going over the concepts: - -[![Chocolatey's Package Builder - Package Builder CLI and Scripting](/assets/images/package-builder/package-builder-cli-video.png)](https://www.youtube.com/watch?v=6TXY5Ie-3wg&list=PLfn-TaDnc1us5X-PVlxW8M1h-6mXEXZSG&index=1 "Chocolatey's Package Builder - Package Builder CLI and Scripting") - -Quickly script out creating packages for your entire organization's cache of software, allowing you to completely automate your Windows installations in moments, not months. You can do that with a simple script: - -~~~powershell -# Path to your installers, will navigate subdirectories -$path = '\\company.file.server\installers' - -# Generate packages over supported types of files -$supportedTypes = @('.exe', '.msi', '.7z', '.zip', '.msu', '.msp') -Get-ChildItem -Path $path -Recurse | ?{ - $extension = [System.IO.Path]::GetExtension($_.Name) - $supportedTypes.Contains($extension) - } | %{ - Write-Host "$($_.FullName)" - # Run choco new against the installer - & choco new --file "$($_.FullName)" --build-package --outputdirectory $pwd -} -~~~ - -As you see this script, it is doing the following: -* Taking a path to where installers, zips, etc are located (`$path = '\\company.file.server\installers'`) -* Setting up support types of files to use with Package Builder (`$supportedTypes = @('.exe', '.msi', '.7z', '.zip', '.msu', '.msp')`) -* Looping over all that it finds in that folder and all subdirectories (`Get-ChildItem -Path $path -Recurse`) -* Find files that apply (`$supportedTypes.Contains($extension)`) -* Run choco new, but point it to the full path to the file (`& choco new --file "$($_.FullName)"`), ask it to attempt to build the package (`--build-package`) and have the output in present working directory (` --outputdirectory $pwd`) - -### Package Builder UI - -Not every person is going to love the command line or may not be familiar with the command line and at Chocolatey we realize this. We've spent countless hours talking to customers and with their feedback we're introducing Package Builder UI. This also gives you an opportunity to transition from existing UI tools while taking advantage of powerful Chocolatey concepts! - -We've prepared a short video to show the power of the UI: -[![Chocolatey's Package Builder - Package Builder UI](/assets/images/package-builder/package-builder-ui-video.png)](https://www.youtube.com/watch?v=qJNKR_PEQqY&list=PLfn-TaDnc1us5X-PVlxW8M1h-6mXEXZSG&index=2 "Chocolatey's Package Builder - Package Builder UI") - -### Generate Packages from Programs and Features - -Another way Package Builder can generate packages is based on looking at what is installed on a system in Programs and Features. This gives you lightning quick ramp up time in both package and automating your Windows software installations! - -[![Chocolatey's Package Builder - Generate Packages from Programs and Features Automatically!](/assets/images/package-builder/package-builder-programs-features-video.png)](https://www.youtube.com/watch?v=Mw_ReipnskI&list=PLfn-TaDnc1us5X-PVlxW8M1h-6mXEXZSG&index=3 "Chocolatey's Package Builder - Generate Packages from Programs and Features Automatically!") - -> :choco-info: **NOTE** -> -> To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b. - -### More business concepts - -![auto package creation/synchronize](/assets/images/gifs/choco_business_features.gif) - -## Options and Switches - -When running `choco new` in the Business editions, pass the following: - -~~~sh - --file, --url=VALUE - Inspect a file (native installer, zip, patch/upgrade file, or remote url - to download first) to to completely create a package with proper silent - arguments! Can be 32-bit or 64-bit architecture. Available in Business - editions only. - - --file64, --url64=VALUE - Optional - used when specifying both a 32-bit and a 64-bit file. Can be - an installer or a zip, or remote url to download. Available in Business - editions only. - - --keepremote, --originallocation, --original-location, --useoriginallocation, --use-original-location, --useoriginalfileslocation, --use-original-files-location - Use Original Files Location - when using file or url, use the original - location in packaging. Available in Business editions only. - - --checksum, --downloadchecksum, --download-checksum=VALUE - Download Checksum - checksum to verify File/Url with. Defaults to empty. - Available in Business editions only. - - --checksum64, --checksumx64, --downloadchecksumx64, --download-checksum-x64=VALUE - Download Checksum 64-bit - checksum to verify File64/Url64 with. - Defaults to empty. Available in Business editions only. - - --checksumtype, --checksum-type, --downloadchecksumtype, --download-checksum-type=VALUE - Download Checksum Type - checksum type for File/Url (and optional - separate 64-bit files when specifying both). Used in conjunction with - Download Checksum and Download Checksum 64-bit. Available values are - 'md5', 'sha1', 'sha256' or 'sha512'. Defaults to 'sha256'. Available in - Business editions only. - - --pauseonerror, --pause-on-error - Pause on Error - Pause when there is an error with creating the package. - Available in Business editions only. - - --buildpackage, --build-package - Build Package - Attempt to compile the package after creating it. - Available in Business editions only. -~~~ - -## FAQ - -### How do I take advantage of Package Builder? - -You must have a [Business edition of Chocolatey](https://chocolatey.org/compare). Business editions are great for organizations that need to manage the total software lifecycle. - -### I'm a licensed customer, now what? - -When you run `choco new`, you can add `--file` and point Chocolatey at the installer file and let Chocolatey figure out everything for creating a package and the silent arguments and wrap that around the installer. - -### Will this become available for lower editions of Chocolatey? - -Package Builder will only be available in C4B (Chocolatey for Business). - -### How does it work? - -It inspects the installer file using a series of rules that helps determine the installer type. From there it builds a package with the information it is able to extract from the installer. - -### What types of extensions are supported? - -Package Builder supports `.exe`, `.msi`, `.msu`, `.msp`, `.7z`, and `.zip`. - -### Will it catch all types of installers? - -It is able to detect 12 types of installers currently. - -### Does it always find the silent uninstall arguments? - -In over 70% of the cases it will, but not always. Even with this in mind, it still removes 90% of the packaging work. When it can't create a fully unattended softare deployment, it will create a TODO file for you to complete. See the next question on how to handle cases where it can not. - -### This was unable to detect custom installer arguments. - -Unfortunately, some installers out there are just a pain to work with. In the case of custom installers, you may be able to find the silent arguments for install and uninstall by searching online. If you can not find anything, consider unpacking the installer and putting the software binaries directly in the package. - -### Does it create auto unattend files? - -Unfortunately, it is not able to do this. See the [automatic internalize and recompile packages feature](xref:automate-package-internalization) to take advantage of thousands of existing packages without a need for internet access. - -### Does it work with zip archive? - -Yes, but somewhat naively. It will generate the packaging to unpack the archive for both 7z and zip files. - -### Does this work with keeping the installer on a UNC share or elsewhere yet? - -Yes, as of Licensed version v1.6.0+. Use `--use-original-location`. - -## Common Issues and Resolutions - -### I get "Name is required. Please pass in a name for the new package." - -This occurs when you are not running Chocolatey for Business or don't have your client properly licensed. Please see [licensed installation](xref:setup-licensed) for more details. diff --git a/input/en-us/features/package-internalizer.md b/input/en-us/features/package-internalizer.md deleted file mode 100644 index add1690f0f..0000000000 --- a/input/en-us/features/package-internalizer.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -Order: 110 -xref: package-internalizer -Title: Package Internalizer (C4B) -Description: Automatically internalize/recompile existing packages -RedirectFrom: docs/features-automatically-recompile-packages ---- - -Automatically Internalize/Recompile Existing Packages (Business and MSP Editions Only) - -There are thousands of existing packages on the [community repository](https://community.chocolatey.org/packages) that are a tremendous resource when it comes to creating packages that have software that can sometimes be tricky! Unfortunately you may be wary of using those packages without changes because many of those packages are subject to distribution rights and thus have an internet dependency (which creates both [trust and control issues](xref:community-packages-disclaimer)). There is a process for downloading and internalizing packages to use internal or embedded locations for that software that is called **internalizing** (also known as recompiling). - -Chocolatey for Business is able to automatically download packages and resources, edit the scripts, and recompile packages to internalize and remove internet dependencies from those packages, saving you hours of time in [manually internalizing/recompiling packages](xref:recompile-packages)! - -## Usage - -Call `choco download` with options including the name of an existing package for Chocolatey for Business to download and download all existing remote resources. - -![Internalize Existing Packages, Recompiling Resources - if you are on https://docs.chocolatey.org/en-us/guides/create/recompile-packages, see commented html below for detailed description of image](/assets/images/features/features_recompile_packages.png) - - - -## See It In Action - -![automatic recompile](/assets/images/gifs/choco_business_features_recompile.gif) - -> :choco-info: **NOTE** -> -> To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b. - -## Options and Switches - -When running `choco download` in the Business editions, pass the following: - -~~~sh - --outputdirectory=VALUE - OutputDirectory - Specifies the directory for the downloaded Chocolatey - package file. If not specified, uses the current directory. - - -i, --ignoredependencies, --ignore-dependencies - IgnoreDependencies - Ignore dependencies when installing package(s). - Licensed editions v1.9.0+ Defaults to false. - - --recompile, --internalize - Recompile / Internalize - Download all external resources and recompile - the package to use the local resources instead. Business editions only - (licensed version 1.5.0+). - - --resources-location=VALUE - Resources Location - When internalizing, use this location for resources - instead of embedding the downloaded resources into the package. Can be a - file share or an internal url location. When it is a file share, it will - attempt to download to that location. When it is an internal url, it - will download locally and give further instructions on where it should - be uploaded to match package edits. Business editions only (licensed - version 1.5.1+). - - --download-location=VALUE - Download Location - OPTIONAL - when internalizing, download the - resources to this location. Used with Resources Location (and defaults - to Resources Location when not set). Business editions only (licensed - version 1.8.3+). - - --append-useoriginallocation, --append-use-original-location - Append -UseOriginalLocation - When `Install-ChocolateyPackage` is - internalized, append the `-UseOriginalLocation` parameter to the - function. Business editions only (licensed version 1.7.0+). Requires at - least Chocolatey v0.10.1 for `Install-ChocolateyPackage` to recognize - the switch appropriately. Overrides the feature - 'internalizeAppendUseOriginalLocation' set to by default to 'False'. -~~~ - -See [download command](xref:choco-command-download) for more information. - -## Resources - -Community posts that include Package Internalizer: - -* [Getting Started With Chocolatey 4 Business & Jenkins CI](https://blog.pauby.com/post/getting-started-with-chocolatey-and-jenkins/) -* [Automating Chocolatey package internalizing with PowerShell](https://winsysblog.com/2017/10/automating-chocolatey-package-internalizing-with-powershell.html) ([archive.org](https://web.archive.org/web/20201025112142/https://winsysblog.com/2017/10/automating-chocolatey-package-internalizing-with-powershell.html)) -* [Recompiling Chocolatey packages](https://winsysblog.com/2017/08/recompiling-chocolatey-packages.html) ([archive.org](https://web.archive.org/web/20210815015512/https://winsysblog.com/2017/08/recompiling-chocolatey-packages.html)) - -## FAQ - -### How do I take advantage of this feature? - -You must have a [Business edition of Chocolatey](https://chocolatey.org/compare) or Chocolatey for MSP. Business editions are great for organizations that need to manage the total software management lifecycle. - -### I'm a licensed customer, now what? - -You can run `choco download` and point it to an existing package name on any remote resource, typically folks point to `https://community.chocolatey.org/api/v2/` and let Chocolatey do all of the work of getting the package and remote resources to recompile the package. - -### How does it work? - -It downloads a package locally. Then it looks at the install script to determine if there are remote resources, which are downloaded to a directory in the package (or with another switch will be placed on a file share or setup for an http location). Then it edits the install script to use the local resources instead and recompiles the package. The process takes about as long as it takes to download the remote resources. - -### Does it work with all types of packages? - -Some packages are already internalized or don't have remote resources. In those cases it will just download the existing package and have it available for pushing to an internal repository. - -### It was not able to download a resource. Why not? - -This feature is in preview, but is able to download/recompile quite a few packages. There are a few that it may have issues with, especially if variables with methods are used (e.g. `$(somevar).Replace(".","")`). In those cases it attempts to warn you ahead of time that it cannot handle those yet. - -Future versions of the licensed edition will support advanced scenarios such as these. - -### Are all packages guaranteed to be compatible? - -Unfortunately not all packages on the community repository are created equal, even with the rigorous moderation process. A few packages do not use the built-in functions for acquiring files from the internet, so they don't lend well to automatic recompiling. Typically Chocolatey will let you know when this is the case and allow you to inspect the package to allow you to finish up the next steps of recompiling. As a future enhancement, it's possible this scenario would also be supported, although it is a very small subset of packages that are created in this way. diff --git a/input/en-us/features/package-reducer.md b/input/en-us/features/package-reducer.md deleted file mode 100644 index 2353ef3955..0000000000 --- a/input/en-us/features/package-reducer.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -Order: 140 -xref: package-reducer -Title: Package Reducer (Pro+) -Description: Reduce the size of your package installations automatically -RedirectFrom: docs/features-package-reducer ---- - -> Reduce the size of your package installations automatically! - -If you have a significant number of Chocolatey packages you manage, you may notice that you also may have a pretty significant space usage under the Chocolatey lib directory. Package reducer automatically decreases the size of nupkg files to around 5KB and removes installers and zips automatically from your package install directories. This may allow you to save GBs of usage for a large amount of packages being managed! - -## Automatic - -### Usage - -When you normally create packages that embed or download resources, the impact on a system includes the following: - -* A nupkg file size takes up some space - this is like a fancy zip file and may contain binaries -* Files extracted or downloaded to the package directory - this may include zips and installers -* The actual install location if using an installer -* MSI cached by Windows - Windows caches the complete MSI binaries - -Typically with this in mind, the size of nupkg could account for an up to 4x impact on a system considering the above. So we typically recommend organizations set a comfortable threshold for package sizes (around 500MB) before splitting out binaries to downloaded resources. - -Package Reducer nearly removes that need as it reduces the nupkg file to 5KB by removing all the embedded files. Then it takes it a step further and removes zip and installers from the package directory automatically (configurable by a feature switch, see [Setup](#setup)). - -When you turn on Package Reducer, the first two items above no longer take up any significant space. This can reduce space usage in the order of GBs for some installations of Chocolatey. - -With Package Reducer: - -* nupkg file is reduced to 5KB or less, no matter the size on install -* zips / installers are automatically removed from the package directory if they are found - -The following file extensions are removed automatically: - -* 7z / zip / rar / gz / tar / sfx -* iso -* msi / msu / msp -* exe files if they are detected to be an installer - -So the space usage impact changes to what you'd normally experience outside of Chocolatey: - -* the actual install location (package directory, Program Files, etc) -* MSI cache for MSIs - -#### Requirements - -* Chocolatey (`chocolatey` package). -* Chocolatey Licensed Edition -* Chocolatey Licensed Extension (`chocolatey.extension` package). - -#### Setup - -To turn on Package Reducer, you need to run the following: - -* `choco upgrade chocolatey.extension ` -* `choco feature enable --name reduceInstalledPackageSpaceUsage` -* If you want to limit to just nupkg files being reduced and not automatically removing zips and installers, run the following: `choco feature enable --name reduceOnlyNupkgSize` - -### See It In Action - -![Package Reducer - if you are on https://docs.chocolatey.org/en-us/features/package-reducer, see commented html below for detailed description of image](/assets/images/features/features_package_reducer.png) - - - -> :choco-info: **NOTE** -> -> To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b. - -### Package-specific Control Of Package Reducer - -It is possible to control Package Reducer at a package level. This is useful where you have enabled `reduceInstalledPackageSpaceUsage` globally, but wish to maintain the -files within a particular package (perhaps a portable package, or binary package). There are 2 options available at the package level to control behavior: - -#### Skip Entire Reducer Functionality - -To completely bypass Package Reducer during a `choco install` or `choco upgrade` operation, add a `.SkipReducer` file to the root of your package. - -#### Skip Extracted Files - -To bypass reducer for extracted files in a package, add a `.SkipReducerFiles` file to your package. This is the same as enabling `ReduceOnlyNupkgSize`. - -### Options and Switches - -Global Config Setting: - - * `reduceInstalledPackageSpaceUsage` - Reduce Installed Package Size (Package Reducer) - Reduce size of the nupkg file to very small and remove extracted archives and installers. - - -`choco install` / `choco upgrade` provide the following option(s): - -~~~ - --reduce, --reduce-package-size, --deflate, --deflate-package-size - Reducer Installed Package Size (Package Reducer) - Reduce size of the - nupkg file to very small and remove extracted archives and installers. - Overrides the default feature 'reduceInstalledPackageSpaceUsage' set to - 'False'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/package-reducer - - --no-reduce, --no-reduce-package-size, --no-deflate, --no-deflate-package-size - Do Not Reduce Installed Package Size - Leave the nupkg and files alone - in the package. Overrides the default feature - 'reduceInstalledPackageSpaceUsage' set to 'False'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/package-reducer - - --reduce-nupkg-only, --deflate-nupkg-only - Reduce Only Nupkg File Size - reduce only the size of nupkg file when - using Package Reducer. Overrides the default feature - 'reduceOnlyNupkgSize' set to 'False'. Licensed editions only. - See https://docs.chocolatey.org/en-us/features/package-reducer -~~~ - -### FAQ - -#### How do I take advantage of this feature? - -You must have a [licensed edition of Chocolatey](https://chocolatey.org/pricing) (Pro, MSP, or Business) and use the community package repository to install/upgrade packages. Pro is a personal, named license that costs about the price of a lunch outing per month and comes with several other features. Business editions are great for organizations that need to manage the total software management lifecycle. MSP editions are for managed service providers and contain the same features as Pro (minus VirusTotal integration). - -#### I'm a licensed customer, now what? - -Once you have set up the feature(s), it will automatically reduce the size of the packaging on install and upgrade. - -#### How does it work? - -It just works. When you install or upgrade a package, it will automatically reduce the size of the installation directory if you've set up Package Reducer properly. - -#### How do I turn this feature on? - -* Globally - `choco feature enable --name reduceInstalledPackageSpaceUsage` -* Per command - use the option `--reduce-package-size` with install/upgrade commands. - -#### How do I turn this feature off? - -* Globally - `choco feature disable --name reduceInstalledPackageSpaceUsage` -* Per command - use the option `--no-reduce-package-size` with install/upgrade commands. - -#### Can I just deflate nupkg file sizes? - -Yes! - -* Globally - `choco feature disable --name reduceInstalledPackageSpaceUsage` -* Per command - use the option `--reduce-nupkg-only` with install/upgrade commands. - -#### Can I apply reducer to already installed packages? - -See the next section, the `choco optimize` command. - -## Optimize Command - -Package Reducer's Package Optimizer is available in all licensed editions. It is similar to the automatic reduction, except it reduces the size of existing installations. - -With Package Optimizer: - -* nupkg file is reduced to 5KB or less, no matter the size. -* zips / installers are automatically removed from the package directory if they are found. -* zips / installers are removed from TEMP cache if found. - -The following file extensions are removed automatically: - -* 7z / zip / rar / gz / tar / sfx -* iso -* msi / msu / msp -* exe files if they are detected to be an installer - -### Usage - -~~~sh -choco optimize [] -~~~ - -#### Requirements - -* Chocolatey (`chocolatey` package) -* Chocolatey Licensed Edition -* Chocolatey Licensed Extension (`chocolatey.extension` package) - -### Examples - -~~~sh -choco optimize -choco optimize --reduce-nupkg-only -~~~ - -### See It In Action - -![choco optimize - if you are on https://docs.chocolatey.org/en-us/features/package-reducer, see commented html below for detailed description of image](/assets/images/features/features_package_reducer_optimize.png) - - - - -### Options and Switches - -~~~sh - --reduce-nupkg-only, --deflate-nupkg-only - Reduce Only Nupkg File Size - reduce only the size of nupkg file when - using Package Optimizer. Licensed editions only. -~~~ - - -### FAQ - -#### How do I take advantage of this feature? - -You must have a [licensed edition of Chocolatey](https://chocolatey.org/pricing) (Pro, MSP, or Business) and use the community package repository to install/upgrade packages. Pro is a personal, named license that costs about the price of a lunch outing per month and comes with several other features. Business editions are great for organizations that need to manage the total software management lifecycle. MSP editions are for managed service providers and contain the same features as Pro (minus VirusTotal integration). - -#### I'm a licensed customer, now what? - -You can just run `choco optimize`. Couple it with package reducer features to automatically ensure your Chocolatey installation stays very small. - -#### How does it work? - -It goes through all existing packages and removes unnecessary installers and zips. It also deflates nupkg files down to 5KB or less. diff --git a/input/en-us/features/package-synchronization/automatic-sync.md b/input/en-us/features/package-synchronization/automatic-sync.md deleted file mode 100644 index e61109bcf6..0000000000 --- a/input/en-us/features/package-synchronization/automatic-sync.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -Order: 10 -xref: automatic-sync -Title: Automatic Sync (Pro+) -Description: Ensure that any operation on an application, i.e. it is uninstalled, or upgraded, is tracked within Chocolatey as well ---- - -## Automatic Synchronize - -In all licensed editions, Chocolatey syncs the state of **already installed Chocolatey packages** (nupkg files) to the state of the software they are linked up with - so if the software is uninstalled or upgraded outside of Chocolatey, it removes the package or notes the upgrade. This behavior is known as automatic synchronization or autosync for short. There is also choco sync, which is different and is covered in [Sync Command](#sync-command) below. - -There is an important distinction between packages and software to understand with Chocolatey. Chocolatey manages packages (nupkg files), and packages manage software. Many packages are what we call "installer packages" - packages that manage an installer and an installation into Programs and Features. Once that software is in Programs and Features, it could be manipulated outside of Chocolatey. If it is removed without the command going through Chocolatey, open source Chocolatey will still have the package installed (which is technically correct from a package manager state, but incorrect based on expectations). With open source you end up with a disconnect if you are not careful. Licensed editions of Chocolatey are able to see system state and correct this discrepancy with autosync by updating the state of the package based on what has occurred outside of Chocolatey. - -For software management, which encompasses package management and above that for Windows, the state of the software is really what should be reflected with those installed packages. So if that software has been uninstalled from Programs and Features or upgraded outside of Chocolatey, autosync removes those packages to match that state or notes the upgrade (note it doesn't change the version of the package - that's much trickier to get correct). - -As commercial editions lean more towards software management, they have much better system integration. Autosync is great for ensuring that Chocolatey matches the state of changes on the system for what the packages it is tracking. - -### Usage - -> :choco-warning: WARNING -> -> The following image shows this behavior in Chocolatey CLI v1.x. Chocolatey CLI v2.x has the same behavior, but uses `choco list` instead of `choco list -lo` to list local packages. - -![Automatic Synchronize - if you are on https://docs.chocolatey.org/en-us/features/package-synchronization, see commented html below for detailed description of image](/assets/images/features/features_synchronize.png) - -In the image above, someone manually removed the 1Password software. On the next run of Chocolatey, auto sync sees the software has been removed, so it removes the package tracking to that software in response to those system changes. - - - -#### Automatic Updating Software? - -When you have software like Google Chrome that automatically updates, it is recommended typically that you pin the package to let the software automatically upgrade. Chocolatey's autosync will track the software updates in the background and store those which will be helpful if you later remove the software from Programs and Features directly or want to run choco uninstall on the package to remove the software. - -#### More Details On External Upgrades - -You could also upgrade the software directly outside of Chocolatey, which would similarly create a discrepancy between the software being on a newer version than the package shows. - -Chocolatey's autosync understands that an upgrade occurred and tracks that for the software, but not the packaging. So you won't see anything visual that indicates the sync as the package version will remain the same. - -> :choco-info: **Why doesn't Chocolatey upgrade the package version?** -> -> There is not always a one to one line up between package version and software version. The version of software you think you are based on the software telling you and what that software reports as the version in the registry are different many times, unfortunately. This makes it very difficlt to update a package version correctly. - -For example, for the longest time Google Chrome had a version number in the registry at 65.x when the version being displayed to users was at like 59.x. The packaging was at 59.x following what people note as the version based on what Google Chrome tells them. This is just one of many examples. - -> :choco-info: **Software version tracking assists in uninstallations where Chocolatey's autouninstaller is invoked.** - -If the software is an MSI, the Product Guid is used for managing uninstalls. Guess what typically changes on every upgrade? Yes, the Product Guid. So autosync is keeping track of the new ones as the software automatically upgrades. Without tracking that, if you were to say `choco uninstall googlechrome` without autosync and there was no `chocolateyUninstall.ps1` in the package, then the software could potentially be left on the system because Chocolatey's automatic uninstaller wouldn't have the right Product Guid and thus be unable to handle software uninstallation. - -### See It In Action - -![auto package creation/synchronize](/assets/images/gifs/choco_business_features.gif) - -> :choco-info: **NOTE** -> -> To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b. - -### Options and Switches - -There are none - automatic sync just happens every run. - -### FAQ - -#### How do I take advantage of this feature? - -You must have a [licensed edition of Chocolatey](https://chocolatey.org/pricing) (Pro, MSP, or Business). Pro is a personal, named license that costs about the price of a lunch outing per month and comes with several other features. Business editions are great for organizations that need to manage the total software management lifecycle. MSP editions contain a subset of the Business edition features. - -#### I'm a licensed customer, now what? - -It just works. - -#### How does it work? - -Chocolatey tracks applications that it installs, so it is able to keep up with those applications as they are upgraded and uninstalled, even outside of Chocolatey. - -#### Sync is not tracking upgrades to applications - -Currently, AutoSync does not support upgrades of the underlying synced Chocolatey Package to reflect new versions of synced software being installed. -Software installers have the following mechanisms to display their information, with no consistent standard: - -- Display Version in the registry (which isn't required and quite a few apps don't populate the field at all) -- Display Name as shown in Programs and Features -- Version field in the uninstaller registry - -Due to the fact that an installer version doesn't have to match the software version (Google's msi is a great example), and the consistency issues with where the information can potentially come from, Chocolatey cannot _reliably_ track application upgrades. diff --git a/input/en-us/features/package-synchronization/index.md b/input/en-us/features/package-synchronization/index.md deleted file mode 100644 index 2cfa10d2fe..0000000000 --- a/input/en-us/features/package-synchronization/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -Order: 200 -xref: package-synchronization -Title: Package Synchronization -Description: Keep changes made to applications outside of Chocolatey in sync -RedirectFrom: docs/features-synchronize ---- - -Chocolatey maintains its own state of the world, while Windows maintains the state of Programs and Features. If an application is upgraded or uninstalled outside of Chocolatey, such as is the case with Google Chrome and its auto updating utility, Chocolatey open source doesn't know about the change. The synchronize features in licensed editions keep Chocolatey's state in sync with Programs and Features, removing possible system-installed state drift. - -* [Automatic Sync (All Licensed Editions)](xref:automatic-sync) -* [Synchronize Command](xref:sync-command) (currently Business edition only - check https://chocolatey.org/compare#compare for availability) -* [All Packages in Programs And Features (C4B)](xref:packages-to-programs) \ No newline at end of file diff --git a/input/en-us/features/package-synchronization/packages-to-programs.md b/input/en-us/features/package-synchronization/packages-to-programs.md deleted file mode 100644 index 7bb4672f99..0000000000 --- a/input/en-us/features/package-synchronization/packages-to-programs.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -Order: 30 -xref: packages-to-programs -Title: Packages to Programs (C4B) -Description: Add an entry into Add/Remove programs for every package that is under Chocolatey management ---- - -## All Packages in Programs and Features - -In C4B, you can flip a switch and see all packages in Programs and Features, even those packages that don't have underlying native installers! This makes reporting back to legacy inventory reporting systems a snap. - -### Usage - -![All Packages in Programs And Features - if you are on https://docs.chocolatey.org/en-us/features/package-synchronization, see commented html below for detailed description of image](/assets/images/features/features_packages_in_programs_and_features.png) - - - -### Requirements - -* Chocolatey (`chocolatey` package) v0.10.7+. -* Chocolatey for Business (C4B) Edition. -* Chocolatey Licensed Extension (`chocolatey.extension` package) v1.10.0+. - -### Setup - -* `choco feature enable --name showAllPackagesInProgramsAndFeatures` - -### Options and Switches - - Global Feature Setting: - - * `showAllPackagesInProgramsAndFeatures` - Package Synchronizer's Packages In Programs And Features Synchronization - Show all packages in Programs and Features, not just packages that use a native installer. - -### FAQ - -#### How do I take advantage of this feature? - -You must have the [business edition of Chocolatey](https://chocolatey.org/pricing). Business editions are great for organizations that need to manage the total software management lifecycle. - -#### I'm a business customer, now what? - -Once you set the feature, it just works automatically. - -#### How does it work? - -Chocolatey tracks packages that manage natively installed software. For packages that are zip archives or configuration, Chocolatey will add an entry into Programs and Features based on the nuspec. It's smart enough not to add an entry for a meta-package - say `notepadplusplus` and `notepadplusplus.install` are installed. The meta-package would be `notepadpluplus`. - -### Packages in Programs and Features Known Issues - -* MSU type packages will show up - Chocolatey doesn't automatically track Windows Updates types of installers. So if you install WMF 5 through Chocolatey and turn this feature on, it will show up as well. -* You must run choco at least one more time after setting the feature for it to take effect. So flip the feature and then run `choco -v`. diff --git a/input/en-us/features/package-synchronization/sync-command.md b/input/en-us/features/package-synchronization/sync-command.md deleted file mode 100644 index 44e8ea14d4..0000000000 --- a/input/en-us/features/package-synchronization/sync-command.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -Order: 20 -xref: sync-command -Title: Choco Sync Command (C4B) -Description: Use choco sync to bring already installed applications under Chocolatey management ---- - -## Sync Command - -Starting in 1.9.0 of the licensed extension, sync has been added as a preview feature for organizations to try out. Currently Business edition only, but expected to be in Pro+ at some point - check https://chocolatey.org/compare#compare for availability. - -Sync looks at all software that is in Programs and Features that is not being managed with Chocolatey packages and brings them under management. This means you can run one command and suddenly, all of the software installed on a machine is under management by Chocolatey! - -### Usage - -To synchronize your system, Simply call `choco sync` and Chocolatey will ensure that all software in Programs and Features comes under Chocolatey management and provides you the packages/package sources so you can add them to source control for managing those packages over time. - -#### Setup - -At 1.9.0, sync is in preview. You need to turn it on by enabling the feature `allowPreviewFeatures`: - -* `choco feature enable --name allowPreviewFeatures` - -### See it in action - -We've prepared a short video to show sync in action: - -[![Chocolatey's Package Synchronizer - Sync Command](/assets/images/features/sync-command-video.png)](https://youtu.be/tzSsYHYsjf4 "Chocolatey's Package Synchronizer - Sync Command") - -> :choco-info: **NOTE** -> -> To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b. - -In the following image, sync is run on a system that has 18 applications installed and a base Chocolatey for Business install. Note after running sync, all software on the machine is now being managed by Chocolatey. - -![Chocolatey's Package Synchronizer Sync Command - if you are on https://docs.chocolatey.org/en-us/features/package-synchronization, see commented html below for detailed description of image](/assets/images/features/features_choco_sync.png) - - - -### Options and Switches - -The following are available in the [choco sync](xref:choco-command-sync) command. - -~~~ - --id=VALUE - Id - The Display Name from Programs and Features - - --out, --outdir, --outputdirectory, --output-directory=VALUE - OutputDirectory - Specifies the directory for the generated Chocolatey - package file(s). If not specified, uses a subdirectory of the current - directory. -~~~ - -### FAQ - -#### How do I take advantage of this feature? - -You must have the [business edition of Chocolatey](https://chocolatey.org/pricing). Business editions are great for organizations that need to manage the total software management lifecycle. - -#### I'm a business customer, now what? - -You would periodically run `choco sync`. - -#### How does it work? - -Chocolatey takes a look at all software in Programs and Features that is not under Chocolatey management, generates packages on the fly and baselines them under the Chocolatey install, ensuring all of the links are tracked. - -#### Do I get the packages to add to source? - -Yes! Chocolatey will tell you the location of the sync files so you can put them into source control. - -#### Some packages have a TODO list - -Generating packages on the fly from Programs and Features for non-MSI installers doesn't provide everything necessary to ensure an actual install. So when you take those packages back to source, you will need to finish out the packaging for those so that later when you upgrade, things will work appropriately. - -#### How do I get machine parseable output? - -Use `-r`. `choco sync -r`. - -#### What if I have an existing package that is just not tracking to Programs and Features? - -Synchronize can recognize existing packages and sync to those as long as the name of the package is a close match to the software name (e.g. Google Chrome becomes either google-chrome or googlechrome). - -### Sync Command Known issues - -* Any packages you've installed side by side (`-m`) will show up every time during sync. -* If you have both a 64-bit and 32-bit version of some software installed, sync will track to one on the first run and the other on the next run. This is not a normal scenario. \ No newline at end of file diff --git a/input/en-us/features/package-throttle.md b/input/en-us/features/package-throttle.md deleted file mode 100644 index 352ec6d152..0000000000 --- a/input/en-us/features/package-throttle.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -Order: 190 -xref: package-throttle -Title: Package Throttle (Pro+) -Description: Use Chocolatey in low bandwidth environments -RedirectFrom: docs/features-package-throttle ---- - -> Use Chocolatey in low bandwidth environments - -By default, Chocolatey downloads packages and any resources the packages use as fast as it can. In most cases, this is exactly the behavior you want. However, low bandwidth areas would be overwhelmed with this behavior and so you need to slow Chocolatey down. Package Throttle covers these low bandwidth scenarios automatically. - -## Usage - -Adding the option or config setting for maximum download rate will slow down the speed a package and any resources are downloaded to a particular machine. This is done in "bit per second" (b/s or bps), which is a common unit of data transmission rate (bandwidth) in computers. The symbol bps is often pronounced "bips." - -A good way to find what you need is to translate from Kbps to bits: [Google Kbps to bps](https://www.google.com/search?q=2+Kb/s+%3D+?+bps) or KB/s (bytes) to bits: [Google KB/s to bps](https://www.google.com/search?q=2+KB/s+%3D+bps). - -### Requirements - -* Chocolatey (`chocolatey` package) v0.10.7+. -* Chocolatey Licensed Edition. -* Chocolatey Licensed Extension (`chocolatey.extension` package) v1.10.0+. - -## See It In Action - -![Package Throttle downloading a package and resources - - if you are on https://docs.chocolatey.org/en-us/features/package-throttle, see commented html below for detailed description of image](/assets/images/features/features_package_throttle.png) - - - -> :choco-info: **NOTE** -> -> To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b. - -## Options and Switches - -Global Config Setting: - - * `maximumDownloadRateBitsPerSecond` - The maximum download rate in bits per second. '0' or empty means no maximum. A number means that will be the maximum download rate in bps. Defaults to ''. - - -`choco install` / `choco upgrade` provide the following option(s): - -~~~sh - --bps, --maxdownloadrate, --max-download-rate, --maxdownloadbitspersecond, --max-download-bits-per-second, --maximumdownloadbitspersecond, --maximum-download-bits-per-second=VALUE - Maximum Download Rate Bits Per Second - The maximum download rate in - bits per second. '0' or empty means no maximum. A number means that will - be the maximum download rate in bps. Defaults to config setting of '0'. - Available in licensed editions. - See https://docs.chocolatey.org/en-us/features/package-throttle -~~~ - -## FAQ - -### How do I take advantage of this feature? - -You must have a [licensed edition of Chocolatey](https://chocolatey.org/pricing) (Pro, MSP, or Business) and use the community package repository to install/upgrade packages. Pro is a personal, named license that costs about the price of a lunch outing per month and comes with several other features. Business editions are great for organizations that need to manage the total software management lifecycle. MSP editions are for managed service providers and contain the same features as Pro (minus VirusTotal integration). - -### I'm a licensed customer, now what? - -It works to slow the download rate when you provide the maximum download rate as an argument or as a set feature. - -### How does it work? - -It sees a resource being downloaded and throttles the download to lower download speeds, ensuring it doesn't go over a set number of bits per second during the entire course of the download. - -### Package Throttle didn't slow down the downloads of resources in my package - -Package Throttle only works for resources downloaded with built-in Chocolatey PowerShell functions. It will not be able to slow down downloads using WebClient, and it's an anti-pattern in packaging to use WebClient anyways. - -### How do I turn this feature on? - -* Globally - `choco config set --name maximumDownloadRateBitsPerSecond --value ` -* Per command - use the option `--max-download-bits-per-second="''"` with install/upgrade commands. - -### How do I turn this feature off? - -* Globally - `choco config unset --name maximumDownloadRateBitsPerSecond` -* Per command - don't specify the `--max-download-bits-per-second` option (and don't have the config set) or `--max-download-bits-per-second="'0'"` if you want to temporarily disable it but keep the config setting. diff --git a/input/en-us/features/powershell.md b/input/en-us/features/powershell.md deleted file mode 100644 index 32b94a4dcb..0000000000 --- a/input/en-us/features/powershell.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -Order: 20 -xref: packaging-for-the-masses -Title: Packaging for the masses - PowerShell -Description: At its heart, Chocolatey uses the Windows Automation Language, PowerShell, to perform its different operations ---- - -Released in November 2006, Windows PowerShell, quickly became the defacto way to automate tasks on Windows. Whether it was automating the creation of Users within Active Directory, or configuring/maintaining your Exchange Server, PowerShell was the way to do it. - -When Chocolatey started, it was clear that PowerShell was going to be at the heart of how it works as well, and that continues to this day. - -Within a Chocolatey package, there are three main PowerShell files: - -- chocolateyInstall.ps1 -- chocolateyUninstall.ps1 -- chocolateyBeforeModify.ps1 - -> :choco-info: **NOTE** -> -> Not all of these files are required within every Chocolatey package, as Chocolatey performs a number of tasks automatically, and overriding the default functionality is only required when you want to do something different. - -When a Chocolatey package is installed/uninstalled, these files are executed at [different times](xref:create-packages#during-which-scenarios-will-my-custom-scripts-be-triggered), giving a [package creator](xref:create-your-own-packages) full control over exactly what actions are performed within a package. - -This flexibility allows for the creation of simple packages (that simply execute a native installer) all the way up to highly complicated installations that perform several operations. - -On top of this, Chocolatey ships with a number of [built-in functions](xref:powershell-reference), to help with the specific tasks of installing applications, binaries, zips, and scripts. - -When you need to create your own custom PowerShell functions, Chocolatey provides the ability to create [extension packages](xref:extensions), to allow the sharing of code across multiple packages, rather than duplicating it. \ No newline at end of file diff --git a/input/en-us/features/private-cdn.md b/input/en-us/features/private-cdn.md deleted file mode 100644 index 613d46b365..0000000000 --- a/input/en-us/features/private-cdn.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -Order: 170 -xref: private-cdn -Title: CDN Download Cache (Pro+) -Description: No more 404s! -RedirectFrom: docs/features-private-cdn ---- - -Chocolatey offers a customer CDN cache of download content for [customers](https://chocolatey.org/pricing)! The internet is unpredictable and sometimes sites go down, the cache ensures that the packages on the community repository are not broken by issues with the internet. We lovingly call this the "**No more 404s feature**". - -We do this by caching a copy of the content on our private CDN. This content also gets virus checked and checksummed to verify that it matches what was originally intended by package maintainers and moderators for you to receive. - -## Important Information for Software Vendors - -When our customers download content from you, we may cache a copy of that content on our customer CDN to ensure that later our licensed customers will be able to access that content again. This allows predictable and reliable installations of packages. Like most CDNs, no changes are made, we are simply ensuring the content stays available for our private customers. We are not modifying, selling, renting, leasing, lending, or sub-licensing this content in any way. - -This private content cache is **only** available as a service for our [licensed customers](https://chocolatey.org/pricing). - -If you have questions or **prefer to opt out**, please [contact us](https://chocolatey.org/contact) and select "Software Vendor Opt Out" (vendor requests only please). - -## Usage - -This is mostly automatic, but in case the feature is turned off, you may turn it on by setting the feature `downloadCache` (`choco feature enable --name downloadCache`). - -To see if a package has content cached on the CDN, you can run `choco info packagename` and it will give you detailed information pertaining to a package. - -![choco info packagename](/assets/images/choco_info_cached.png) - -When you install, you will see a message similar to the following when the cached content is used: - -![Pro install with CDN cache](/assets/images/choco_install_cached.png) - -## Options and Switches - -Global Feature: - -* `downloadCache` - Download Cache - use the private download cache if available for a package. - - -`choco install` / `choco upgrade` provide the following option(s): - -~~~ - --sdc, --skipdownloadcache, --skip-download-cache - Skip Download Cache - Use the original download even if a - private CDN cache is available for a package. - Overrides the default feature 'downloadCache' set to 'True'. Licensed - versions only. - - --dc, --downloadcache, --download-cache, --use-download-cache - Use Download Cache - Use private CDN cache if - available for a package. Overrides the default feature 'downloadCache' - set to 'True'. Licensed versions only. -~~~ - -## FAQ - -### How do I take advantage of this feature? - -You must have a [licensed edition of Chocolatey](https://chocolatey.org/pricing) (Pro, MSP, or Business) and use the community package repository to install/upgrade packages. Pro is a personal, named license that costs about the price of a lunch outing per month and comes with several other features. Business editions are great for organizations that need to manage the total software management lifecycle. MSP editions are for managed service providers and contain the same features as Pro (minus VirusTotal integration). - -### I'm a licensed customer, now what? - -When you install packages from the community repository and a private cache becomes available, it will use that cache automatically. You don't have to do anything additional. - -### How do I turn this feature on? - -* Globally - `choco feature enable --name downloadCache` -* Per command - use the switch `--use-download-cache` with install/upgrade commands. - -### How do I turn this feature off? - -* Globally - `choco feature disable --name downloadCache` -* Per command - use the switch `--skip-download-cache` with install/upgrade commands. - -### Is the content modified? - -No, this is the original content as it would have been downloaded. - -### Is the content publicly available? - -No, this is a private CDN cache available only for [licensed customers](https://chocolatey.org/pricing). - -### Why isn't a cache available for x package? - -There are a variety of factors that go into suitability for a package. - -* If the software vendor has opted out, there will be no cache for a package that uses that software. -* If the package doesn't actually download anything, there will be no cache. -* If the package downloads resources, but not in the recommended way, there may not be a cache available. - -### Does this grant me a license to the software? - -No, you still need to work with the software vendor to obtain a license, if required. - -### I'm a vendor and wish to opt out. - -Please see [important information for software vendors](#important-information-for-software-vendors). diff --git a/input/en-us/features/self-service-anywhere.md b/input/en-us/features/self-service-anywhere.md deleted file mode 100644 index e75423ddba..0000000000 --- a/input/en-us/features/self-service-anywhere.md +++ /dev/null @@ -1,267 +0,0 @@ ---- -Order: 90 -xref: self-service-anywhere -Title: Self Service Anywhere (C4B) - Support modern workforce -Description: Install packages as a non-administrator user -RedirectFrom: docs/features-agent-service ---- - -## Summary - -> Empower your users and give your IT folks the precious gift of time to invest into taking your organization to the next level! - -The Chocolatey Agent service allows you to go further with your software management, bringing Chocolatey to desktop users in organizations that have controlled environments. This provides users in controlled environments more empowerment and instant turn around on required software. This frees up IT folks and admins time to spend on making the organization even better. - -The Chocolatey agent enables multiple features: - -* The Background Service, aka Self-Service Anywhere -* Conmmunication to Chocolatey Central Management (CCM) - * Reporting information to CCM - * Deployments from CCM (endpoint management tasks) - -The Chocolatey Agent can be independently configured to support any or all of these modes of operation independently. - -## Chocolatey Background Service / Self-Service Installer - -When an administrator installs the agent, they can configure Chocolatey to use background mode so that non-administrators can still perform installations of approved software as configured by an administrator. - -Why this is desirable: - -* Users do not need to be administrators but are still empowered to install and upgrade software (functions are configurable with Chocolatey Extension v1.12.4+) -* Users can **only** run install and upgrade in an administrative context by default. This is configurable to other commands as of Chocolatey Licensed Extension 1.12.4+.. -* Shortcuts, desktop icons, etc created through Chocolatey functions will end up with the proper user (still coming). -* Users can only install approved software based on admin configured sources. -* This frees up precious IT bandwidth to work on other engagements. -* Empowers users, so they feel more in control. - -This makes for happy users and happy admins as they are able to move quicker towards a better organization. - -### Background Service Restricted Options - -> :choco-info: **NOTE** -> -> The restricted options cannot be customised at this time. We will add this ability in upcoming versions. -> -> The options restrictions affect the following versions of Chocolatey Agent and Chocolatey Licensed Extension: -> -> | Product | Versions Affected | -> |------------------------------ |--------------------------------------------------------------- | -> | Chocolatey Agent | 1.1.3 and later 1.x versions, and 2.1.1 and later 2.x versions | -> | Chocolatey Licensed Extension | 5.0.4 and later 5.x versions, and 6.1.1 and later 6.x versions | - - -Chocolatey CLI allows a number of different options that can be used to configure package management when using the Background Service. To help minimise issues and improve security, the following options, along with their aliases, cannot be used in Chocolatey CLI or Chocolatey GUI when using the Background Service: - -* Added in Chocolatey Agent 1.1.3 / 2.1.1 and Chocolatey Licensed Extension 5.0.4 / 6.1.1: - * `--cache-location` - * `--install-arguments` - * `--not-silent` - * `--install-args-global` - * `--install-arguments-sensitive` - * `--install-directory` -* Added in Chocolatey Agent 1.1.4 / 2.1.2 and Chocolatey Licensed Extension 5.0.5 / 6.1.2: - * `--allow-empty-checksums` - * `--allow-empty-checksums-secure` - * `--download-checksum` - * `--download-checksum-x64` - * `--from-programs-and-features` - * `--ignore-checksums` - * `--override-arguments` - * `--proxy` - * `--proxy-bypass-list` - * `--proxy-bypass-on-local` - * `--skip-virus-check` - * `--uninstall-arguments` - * `--uninstall-arguments-sensitive` - * `--use-system-powershell` - * `--virus-positives-minimum` -* Added in Chocolatey Agent 2.1.3 and Chocolatey Licensed Extension 6.2.0: - * `--ignore-pinned` - -### See It In Action - -* Chocolatey's Self-Service Installer - Part 1: - -[![Chocolatey's Self-Service Installer - Part 1](/assets/images/features/features_selfservice_video1.jpg)](https://www.youtube.com/watch?v=Thw9GpQaZ6M "Chocolatey's Self-Service Installer - Part 1") - -* Chocolatey's Self-Service Installer - Part 2: - -[![Chocolatey's Self-Service Installer - Part 2](/assets/images/features/features_selfservice_video2.jpg)](https://www.youtube.com/watch?v=BnnAwFftUwU "Chocolatey's Self-Service Installer - Part 2") - -> :choco-info: **NOTE** -> -> To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b. - -Consider the following image: - -![Attempting to install software as non-admin - if you are on https://docs.chocolatey.org/en-us/features/self-service-anywhere, see commented html below for detailed description of image](/assets/images/features/features_non_admin_installer.png) - - - -This is the status quo for a non-administrative user. Can't install software without the help of an administrator. That takes up time, time for both the user waiting to get work done and the IT admin that performs the work. - -Now, how does that change once we have background mode? - -![Installing software with Chocolatey's background mode from the command line. - if you are on https://docs.chocolatey.org/en-us/features/self-service-anywhere, see commented html below for detailed description of image](/assets/images/features/features_non_admin_selfservice.png) - - - -Once you've configured background mode and configured approved sources for installation, a user can install only those approved applications using the command line or the Chocolatey GUI. - -Now, if a user wants to install from a non-approved source, they are met with the following message: -![Not able to install from custom source](/assets/images/features/features_non_admin_custom_source_error.png) - -This ensures non-admin users can only install from sources that you configure. - -## Scenarios With Self-Service - -We'll add more scenarios as we come across them from questions, etc. This is meant to address situations you might find yourself in and how best to apply recommendations work through them. - -### Managing Very Large Installation Media - -If you are managing something like SQL Server, Office, or Autodesk, you may already know you need to split the binaries away from the Chocolatey packaging. Where do you put it and how can you ensure it can be installed with background service? - -#### Option 1 - Binary/Raw Repository - -You can store big binaries in a raw/binary repository that comes with the following repository servers: Nexus, Artifactory, and ProGet. You could also just put things on a web host that gives bare downloads when accessed. - -**Pros:** -* Very reliable - once files are in the binary/raw repository, moving them around would require being very intentional. Since the binary/raw repository sits directly next to the Chocolatey package repositories, they are going to work well together. -* Low maintenance - you don't need to remember to add new computers to any AD groups. -* Could be accessed anywhere - aside from open credentials being necessary right now, once that is adjusted in Chocolatey itself, this would allow you to get to the installation media from anywhere in the world if you chose to open it up that way. - -**Cons:** -* Initial setup - it will take a moment to get this setup, but it can be done really fast if you already followed Chocolatey recommendations on using Nexus, Artifactory, or ProGet for your repository needs. -* No credentials on binary/raw repository - The Chocolatey built-in functions like `Get-ChocolateyWebFile` don't have the ability to directly pass credentials yet. -* Requires a local download - if the installation media is big enough, you may prefer installing from a network share and not want to download the components first to each machine. - -#### Option 2 - File Share - -You may choose that you want to store files on a network share as that is where you may have a lot of your installation media currently and you don't want to set up somewhere else that you would need to duplicate what is already done. - -Just like in the cases of Puppet, Chef, or other things that run under a Windows Service, the account that runs the Chocolatey Agent by default is a local Windows account. So it is not going to have permission to see a file share by default. There are two methods you can employ to handle this situation. - -Pick from one of two different methods: - -1. Use a LDAP account for the service - you can always run the service under a different user. See [Agent Install Options](xref:setup-agent#chocolatey-agent-install-options). -1. Give the computer read access to the share - If you are on Active Directory, you can add all computers to a global group and give that group read access to the share. This requires being explicit on that with no nesting. See [explicit permissions to allow local accounts access to file shares](xref:setup-agent#im-having-trouble-seeing-packages-on-a-file-share-source). - -**Pros:** -* Easy setup - you are simply creating a file share. -* Enables network installs - no need to download anything locally. - -**Cons:** -* Not very reliable - If a file gets deleted, renamed, or moved, you now have a broken package you need to go fix. This could happen simply as the files here may be dual-purposed and other folks don't realize they are breaking your packages. You must be diligent in here that you don't mess things up. -* Can not be used outside of network - if you have clients that need to install packages but are outside your network, they are going to fail. -* Method 2 requires maintenance - every time you add new computers you need to remember to explicitly add them to the AD global group. - -#### Option 3 - File Share Managed Outside of Self-Service - -If you are unable to use one of the two methods to gain access to the file share, your last option is really to manage those packages that have the bigger binaries outside of self-service. - -* Make sure you have the feature `useBackgroundServiceWithSelfServiceSourcesOnly` enabled. -* Create another Chocolatey/NuGet repository and put those non-self-service useable packages in that repository instead. -* When configuring that source on your machines, don't add the `--allow-self-service` to that repository. That repository is now invisible to self-service and won't be considered whenever referring back to the background service. - -**Pros:** -* Same Pros as in Option 2. Additionally: -* Packages being managed separately will be skipped automatically on upgrade all. - -**Cons:** -* Same Cons as seen in Option 2. Additionally: -* You must manage installs/upgrades separately. -* Still can't manage it with other infrastructure management / endpoint management tools either - most tools, like Puppet, Chef, possibly SCCM, are still going to have trouble seeing that file share. Unless of course you have given those Windows services an account that has network share access. - -#### Recommendation - -When you can, prefer option 1 (Binary/Raw Repository). This gives you the most flexibility. However depending on your needs, you may see a combination of any of the above. - -### Managing Non-Silent Installers - -Sometimes you come across non-silent installers. These are things that occur that would block an install/upgrade from finishing until there is a user interaction, like a pop-up or opening a browser and directing to a site. And it doesn't matter what you pass for silent arguments, the installer will still present these user interactions. - -With Chocolatey, like with other deployment or endpoint management tools, an installer must be made completely silent/unattended to work in automated deployment scenarios. - -#### Option 1 - MSI Repackaging - -The best way to handle installers that do not play nice is called MSI repackaging (records installation and produces an MSI you use instead). MSI repackaging technology has been around for about 20 years and once you have that produced MSI, it will work in all deployment scenarios. - -**Pros:** -* Produced MSI can be used in all automation scenarios - works with any deployment scenario, including those that are run by a Windows service. -* Produced MSI is solid - there are unlikely to be issues with deploying this in any environment. -* Not much learning required to create MSI - depending on what tool you use for MSI repackaging, it's really easy to do. -* You can trust produced MSI - you created it, you know nothing is gonna hack your environment with specially crafted scripts in the MSI. -* Can be done reasonably quickly - it doesn't take a lot of time to run MSI repackaging once you are set up, you might want to use a clean VM with a snapshot you can go back to after each time you complete. - -**Cons:** -* You must repackage for each new version of the software -* Media is not the same as the original - what you actually deploy is not the same as the original installation media. -* No examples to look at - read more below. -* Produced binaries still subject to distribution rights - however if you are keeping everything internal, you never need to worry about this. You just can't share what you've done on something like the community repository as it is public. - -> :choco-info: **NOTE** -> -> Unfortunately you are unlikely to find any packages on the Chocolatey Community Repository that are able to take advantage of MSI repackaging - this is due to both distribution rights and verification/security. - -* Redistribution of installation media often requires permission - that would include anything that mimics what is done (like the produced MSI). -* Then verification and security - even if redistribution is allowed, you step into trust and verification of this unknown binary that moderators and the community at large are unlikely to trust. When you are doing MSI repackaging internally and housing the bits on your internal repo, you can typically more fully trust what you are doing there versus some random maintainer on the internet doing similar. - -#### Option 2 - Use Chocolatey Software's Professional Packaging Support Services - -When you are customer, you can engage with Chocolatey Software to create the MSI for you for a flat rate fee. - -**Pros:** -* Same Pros as in Option 1. Additionally: -* Easy - you hand off the media to our team and you get an MSI and Chocolatey package back. -* Affordable - there is a flat rate fee associated. So you pay the same price whether it takes our team 2 hours or 5 days. -* Turnaround is fast - depending on the queue, you can have something in your hands in less than two weeks. -* Built by Chocolatey - these MSIs are produced by our team, so you can trust that it's not someone random person out there making these. - -**Cons:** -* Same Cons as in Option 1. Additionally: -* Turnaround time is 5-10 business days - if you need something in a rush, you may need to complete Option 1. -* Requires prepayment - you must pay for this in advance. -* Each version counts as a use - each time you reach out, including having upgrades for a piece of software, counts as an engagement and is subject to the fee. - -#### Option 3 - Window Automation Scripting - -There are tools like Autohotkey (AHK) and AutoIT that can handle the user interaction for you. The bonus is that you get to use the original installation media and have a script that handles all of the failure points for the non-silent installer. - -**Pros:** -* Uses original installation media - the script clicks the buttons or closes the windows for you -* Script may work with newer versions - the script may not require any updating whenever newer versions of software come out. -* Examples may already exist - the community package repository can use this method to automate badly behaved installers b/c the original installation media is being used. - -**Cons:** -* Requires interactive session - will fail as soon as you have a Windows service attempt to run this in a headless operation. -* Requires learning the automation scripting syntax - if you dislike learning new tools, you will find this an issue. -* Can be fragile - whenever you have tools that are clicking on buttons for you, depending on how the scripts are written, can still be fragile. - -#### Recommendation - -MSI repackaging is always preferred. At the end of creating that, you have something that can be deployed silently with any method you prefer to deploy it with. - -## Chocolatey Central Management - -Chocolatey for Business has centralized reporting and supports endpoint management through [Chocolatey Central Management (CCM)](xref:central-management). On machines that will take advantage of CCM, you will need the Chocolatey Agent installed and properly configured to manage them centrally. - -For more information on Central Management, please see [Chocolatey Central Management](xref:central-management). diff --git a/input/en-us/features/shim.md b/input/en-us/features/shim.md deleted file mode 100644 index 9511499b58..0000000000 --- a/input/en-us/features/shim.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -Order: 80 -xref: shim -Title: Executable shimming (like symlinks but better) -Description: Information on how Chocolatey creates shims to installed executables -RedirectFrom: docs/features-shim ---- - -Shimming is like symlinking, but it works much better. It's a form of redirection, where you create a "shim" that redirects input to the actual binary process and shares the output. It can also work to simply call the actual binary when it shims GUI applications. - -We like to call this "batch redirection that works". - -This also allows applications and tools to be on the "PATH" without cluttering up the PATH environment variable. - -## Benefits - -These are the benefits of creating a shim: - - * Provides an exe file that calls a target executable. - * Runs the target executable where it is, which means all dependencies and other things used are all in the original location - * When items require elevated privileges, shims will raise UAC prompts. - * The exe can be called from powershell, bash, cmd.exe, or other shells just like you would call the target. - * Blocks and waits for command line apps to finish running, exits immediately when running a GUI app. - * Uses the icon of the target if the target exists on creation. - * Works better than symlinks. Symlinks on Windows fall down at file dependencies. So if your file depends on other files and DLLs, all of those need to also be linked. - * Does not require special privileges like creating symlinks (symbolic links) do. So you can create shims without administrative rights. - -## Usage - -Chocolatey automatically shims executables in package folders that are not explicitly ignored, putting them into the `"$($env:ChocolateyInstall)\bin"` folder (and subsequently onto the PATH). This typically resolves to `C:\ProgramData\chocolatey\bin` unless you customized your install options or a non-administrator install. - -These executables can come as part of the package or downloaded to the package folder during the install script. - -Chocolatey ensures the folder `"$($env:ChocolateyInstall)\bin"` in the PATH environment variable, allowing you to put tools on the PATH without cluttering up the PATH. - -## See It In Action - -![Shimming - if you are on https://docs.chocolatey.org/en-us/features/shim, see commented html below for detailed description of image](/assets/images/features/features_shimgen.png) - - - -## Options and Switches - -You pass these arguments to an executable that is a shim (e.g. executables in the bin directory of your Chocolatey install, not choco.exe): - - * `--shimgen-help` - shows this help menu and exits without running the target - * `--shimgen-log` - logging is shown on command line - * `--shimgen-waitforexit` - explicitly tell the shim to wait for target to exit - useful when something is calling a gui and wanting to block - command line programs explicitly have waitforexit already set. - * `--shimgen-exit` - explicitly tell the shim to exit immediately. - * `--shimgen-gui` - explicitly behave as if the target is a GUI application. This is helpful in situations where the package did not have a proper .gui file. - * `--shimgen-usetargetworkingdirectory` - set the working directory to the target path. Useful when programs need to be running from where they are located (usually indicates programs that have issues being run globally). - * `--shimgen-noop` - Do not actually call the target. Useful to see what would happen if you ran the command. - -## FAQ - -### How do I take advantage of this feature? - -This works with all versions of Chocolatey. Just use packages and when those packages have exe files, those are automatically shimmed so they are on the PATH. - -### How does it work? - -Chocolatey uses a tool called ShimGen that inspects an executable and creates a small binary, known as a "shim", that simply calls the executable. Then it places that shim in the `"$($env:ChocolateyInstall)\bin"`. It creates the shim by generating it at runtime based on the actual binary's information. - -### How is this better than symlinks? - -When you symlink a file on Windows, you must symlink all of its dependencies like dlls and config files. If you put that all into the `"$($env:ChocolateyInstall)\bin"` folder to take advantage of being on the PATH, you can quickly see that you will get into a form of "DLL hell" when other executables depend on different versions of the same DLL. You would also need to symlink folders and files for things like plugins, extensions, skins, and other things that are in the original directory. If you are trying to create a symlink to not add more locations to your PATH environment variable, then this particular shortcoming defeats that purpose entirely. - -Shimming by design does not run into this issue. - -### Does it require admin rights? - -No, and this is another thing that sets it apart from symlinks. To create symlinks on Windows, you need to have `SeCreateSymbolicLinkPrivilege`, which is one of the privileges granted to Administrators. - -### Does the shim work with UAC? - -Yes! When a shim detects that elevation is required, it will automatically request elevation. - -### Why not simple batch redirection? - -We tried using batch ("*.bat") files, and it mostly works, but when applications calling other applications expect the file name to be ".exe", a file named "*.bat" doesn't work. Batch files also don't work in all shells, and shims do. - -### Have you thought about shimming in more places? - -Yes, but we have not decided whether shimming Program Files is a good idea yet or not. Packages can explicitly enforce shims with [Install-BinFile](xref:install-binfile). - -### I need to shim a non-exe file. - -If you are creating a package and you need to shim a file that doesn't end in .exe (like a .bat file), you should look at [Install-BinFile](xref:install-binfile). - -### I need to exclude a file from shimming. - -If you are creating a package and you want to skip creation of a shim for a particular file, you can create a "*.ignore" file. - -Set an empty file next to the executable (or where it will be downloaded/unpacked to), sharing the same name with the executable and appending ".ignore". For example, if your file is named "`bob.exe`", you need a file named "`bob.exe.ignore`" (pay attention to case - "`BOB.exe.ignore`" may not work with all versions of Chocolatey). - -[Read more...](xref:create-packages#how-do-i-exclude-executables-from-getting-shims) - -### I have architecture specific binaries to shim - -If you are creating a package where you have two binaries (or sets of binaries) to shim depending on architecture, one for x86 and one for x64, you can put them in sub-folders and the correct one(s) will be shimmed. - -Specifically, include 32-bit binaries in "`tools\x86`" and 64-bit binaries in "`tools\x64`". - -This may eliminate the need to include a "`chocolateyInstall.ps1`" in the package to create "`.ignore`" files for the other architecture. - -### How can I ensure a GUI shim? - -Chocolatey will automatically detect GUI applications and adjust the shim accordingly. The detection may not always be accurate, and older versions of Chocolatey don't handle this, so it's best to create a "*.gui" file to direct the shim creation to be for a GUI application. - -If you are creating a package and want the shim to exit immediately after calling the application, create an empty "*.gui" file next to where the exe file is (or where it will be downloaded/unpacked to), sharing the same name with the executable and appending ".gui". For example, if your file is named "`bob.exe`", you need a file named "`bob.exe.gui`" (pay attention to case - "`BOB.exe.gui`" may not work with all versions of Chocolatey). - -[Read more...](xref:create-packages#how-do-i-set-up-shims-for-applications-that-have-a-gui) - -### A package messed up and should have set up a shim as a GUI. - -Call the shim with `--shimgen-gui` to target the correct behavior. - -### An executable requires being run from the folder where it actually is. - -Call the shim with `--shimgen-usetargetworkingdirectory`. There are badly behaved applications that don't run well from anywhere, and they require some extra help so they will run correctly. diff --git a/input/en-us/features/virus-check.md b/input/en-us/features/virus-check.md deleted file mode 100644 index 2a1210d4fa..0000000000 --- a/input/en-us/features/virus-check.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -Order: 160 -xref: virus-check -Title: Runtime Malware Protection (Pro+) -Description: Virus checking via VirusTotal or Generic scanner -RedirectFrom: docs/features-virus-check ---- - -We are pleased to offer runtime malware protection for our [customers](https://chocolatey.org/pricing)! -Virus checking is available in two flavors - VirusTotal and Generic malware verification. - -Both forms of virus scanning will only scan files **downloaded** from an external source during the package installation process. -Packages which embed the software binaries will not have their binaries scanned by Chocolatey during installation. - -## Usage - -When a binary is not flagged: - -![Virus scan pass](/assets/images/virus_scan_normal.png) - -When a binary is flagged: - -![Virus scan failure](/assets/images/virus_scan_flagged.png) - -### VirusTotal - -We've teamed up with the amazing [VirusTotal](https://virustotal.com/) to offer a second opinion to your built-in anti-virus solution. When your packages download content from the internet, Chocolatey CLI will automatically check the executables prior to running any content. If a certain number of positives have been identified (configurable), Chocolatey CLI will fail the install automatically (but can be overridden). - -VirusTotal scans binaries against over 50 different anti-virus scanners. Chocolatey CLI will use the information based on sending a SHA256 checksum of the binary to VirusTotal and evaluating what the scans have determined. - -By default, the virus scanner is already enabled and set to VirusTotal for Pro licenses. Organizations are usually more wary about reaching out to the internet, so the feature is set to Generic and the virus scanner may not be enabled by default (because it needs configuration). If you need to configure the virus scanner to use VirusTotal, please run the following two commands: - -> :choco-warning: **WARNING** -> -> If package contents are not recognized by VirusTotal they may be uploaded to be scanned, and be viewable in public. If you package internal components we do not recommend you enable this feature with the VirusTotal `virusScannerType`. - - * `choco config set --name virusScannerType --value VirusTotal` - * `choco feature enable --name virusCheck` - -Because some scanners can be quite aggressive and may falsely identify a binary as a false positive for malware, Chocolatey CLI doesn't flag a binary until a certain number of scanners have identified the binary as malware. This number defaults to `5` in the configuration. This means 5 anti-virus scanners need to flag the binary for Chocolatey CLI to stop and fail the install or upgrade. You can adjust this value in two ways, by adjusting the configuration and per Chocolatey CLI command. - -To adjust the configuration value, which will globally set the number, please run the following replacing `##` with the value you want as a minimum: - - * `choco config set --name virusCheckMinimumPositives --value ##` - -If you need to override the minimum number of positives just for one install or upgrade, you can do that by passing `--virus-positives-minimum=VALUE` with your install or upgrade commands. - -### Generic - -If you are an organization, and you do not want to reach out to the internet for virus scan verification, you will want to take advantage of hooking Chocolatey CLI up to your existing AV solution. - -Chocolatey CLI will just need to know the full path to the anti-virus command line executable, the arguments to pass, and valid exit codes (comma separated). -Then you will get the same benefit of runtime virus checking as an added benefit on top of the protection it is already providing. - -If you need to configure the virus scanner to use your built-in anti-virus solution, please run the following two commands: - - * `choco config set --name virusScannerType --value Generic` - * `choco config set --name genericVirusScannerPath --value "full path to av command line"` - * `choco config set --name genericVirusScannerArgs --value "[[File]]"` - * `choco config set --name genericVirusScannerValidExitCodes --value "0, ##"` - * `choco feature enable --name virusCheck` - -The `genericVirusScannerPath` should be the full path to the anti-virus command line executable. What we are looking for is the command line interface to the scanner. - -In `genericVirusScannerArgs`, these are the arguments that Chocolatey CLI will pass to the anti-virus console. Chocolatey CLI will automatically replace `[[File]]` with the full path to the binary that it is scanning. - -In `genericVirusScannerValidExitCodes`, these are exit codes that indicate that a binary is okay. This defaults to `0`, but you can configure this with as many exit codes as necessary by adding them to the configuration as comma separated values. - -#### Windows Defender Example Configuration - -```powershell -choco config set --name="'virusScannerType'" --value="'Generic'" -choco config set --name="'genericVirusScannerPath'" --value="'C:\Program Files\Windows Defender\MpCmdRun.exe'" -choco config set --name="'genericVirusScannerArgs'" --value="-Scan -ScanType 3 -File '[[File]]'" -choco config set --name="'genericVirusScannerValidExitCodes'" --value="'0'" -choco feature enable --name="'virusCheck'" -``` - -## See It In Action - -![Pro install in action](/assets/images/gifs/chocopro_install_stopped.gif) - -> :choco-info: **NOTE** -> -> To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b. - -## Options And Switches - -The following options are added to install and upgrade commands. - -~~~ - --svc, --skipvirus, --skip-virus, --skipviruscheck, --skip-virus-check - Skip Virus Check - Skip the virus check for downloaded files on this ru- - n. Overrides the default feature 'virusCheck' set to 'True'. Licensed - versions only. - - --virus, --viruscheck, --virus-check - Virus Check - check downloaded files for viruses. Overrides the default - feature 'virusCheck' set to 'True'. Licensed versions only. - - --viruspositivesmin, --virus-positives-minimum=VALUE - Virus Check Minimum Scan Result Positives - the minimum number of scan - result positives required to flag a package. Used when - virusScannerType is VirusTotal. Overrides the default configuration - value 'virusCheckMinimumPositives' set to '5'. Licensed versions only. -~~~ - -## FAQ - -### How do I take advantage of this feature? - -You must have a [licensed edition of Chocolatey](https://chocolatey.org/pricing) (Pro, Business, or MSP). Pro is a personal, named license that costs about the price of a lunch outing per month and comes with several other features. Business editions are great for organizations that need to manage the total software management lifecycle. MSP editions contain a subset of the Business edition features. MSPs are only able to use the Generic Virus Scanner. - -### I'm a licensed customer, now what? - -> :choco-warning: **WARNING** -> -> If package contents are not recognized by VirusTotal they may be uploaded to be scanned, and be viewable in public. If you package internal components we do not recommend you enable this feature with the VirusTotal `virusScannerType`. - -When you install a package that download content, those items will automatically be verified if the feature is turned on (it is automatically turned on for Pro users). We don't turn it on automatically in Business editions because many organizations are wary about reaching out to the internet and the generic virus scanner requires additional configuration. - -### How do I turn this feature on? - -> :choco-warning: **WARNING** -> -> If package contents are not recognized by VirusTotal they may be uploaded to be scanned, and be viewable in public. If you package internal components we do not recommend you enable this feature with the VirusTotal `virusScannerType`. - -* Globally - `choco feature enable --name virusCheck` -* Per command - use the switch `--virus-check` with install/upgrade commands. - -You need to provide additional configuration if you are using the Generic virus scanner. - -### How do I turn this feature off? - -* Globally - `choco feature disable --name virusCheck` -* Per command - use the switch `--skip-virus-check` with install/upgrade commands. - -### How do I override the minimum number of positives? - -* Globally - `choco config set --name virusCheckMinimumPositives --value ` -* Per command - use the option `--virus-positives-minimum=` with install/upgrade commands. - -### How does the VirusTotal integration work? - - * After a download, Chocolatey CLI will check a file against Virus Total's scan engines to determine how safe the file is as a secondary check to the virus scanner you may already have running. - * If there are existing scan results, it will determine based on the number of positives whether the file is likely safe or not (you can adjust the minimum positives number up or down). - * If the number is over the minimum positives, it will require you to make the determination on the safety of the file. In other words, it will protect you by failing the install, but it will give you instructions on how to override Chocolatey CLI. - * If Chocolatey CLI doesn't find a virus scan has been completed before, it will ask you if you want to upload the file. It will default to no (some users will have things they don't want pushed publicly). - * Whether or not you choose to upload a file when no scan is found, the virus check will fail the install as a matter of protection. Chocolatey CLI will not make the determination if you got the file you were supposed to get from the source you thought you were getting it from, so it errors on the side of caution. - * A scan across all the engines can take a while, so it will fail with an error and notes on how you can move forward immediately if you trust the file. Virus scans can take up to 15 minutes, so it will request you try again in about 15 minutes. - -### How does VirusTotal verify the binary? - -Chocolatey CLI gets the binary's signature by getting a SHA256 checksum of the binary. A SHA256 checksum is extremely secure and accurate, SHA256 has not been broken. It then submits that value to VirusTotal to see if there are pre-existing results. If there are, due to the checksum, the file is **the *exact* same binary**. Then Chocolatey CLI inspects the results and determines if the file is safe or if it should fail. - -### What if VirusTotal doesn't have results for a binary? - -Chocolatey CLI will ask if you want the binary submitted to VirusTotal to be scanned (if the file is under 500MB). Then it will upload the binary their servers, ask you to try the install again in 15 minutes and fail the install. If this is running as a script, the question will time out after 30 seconds and default to no upload. - -### Do you have plans to offer better integration with particular anti-virus scanners? - -Yes! If you are considering or have a business edition of Chocolatey, please let us know what you need, and we can get that scanner on the list. There are so many virus checking solutions and a generic scanner provides the best opportunity to serve all of them. diff --git a/input/en-us/getting-started.md b/input/en-us/getting-started.md deleted file mode 100644 index 024e8e3bb3..0000000000 --- a/input/en-us/getting-started.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -Order: 70 -xref: getting-started -Title: Getting Started -Description: Introduction to Chocolatey -RedirectFrom: - - docs/getting-started - - docs/gettingstarted ---- - -## What is Chocolatey? - -Chocolatey is a software management solution unlike any you've ever experienced on Windows. Think of it like this - you create a software deployment package using a little PowerShell, then you can deploy it anywhere you have Windows with everything (like Puppet, SCCM, Altiris, Connectwise Automate, etc). - -> Write your deployment once for any software, then deploy it with any solution everywhere you have Windows. - -You know those massively complicated, complex, and expensive software management solutions where you typically need to buy more machines and hire consultants to help you configure/maintain them? Yeah, [that's not us](#requirements). We believe in simple solutions to complex problems. Software on Windows is already complex enough, we've designed our tools to be able to be simple to use, extremely powerful, flexible to fit nearly any situation, to work with your existing infrastructure, and for scale. And the best part is you can take advantage of Chocolatey without any cost (yes, even internally for an organization)! - -### Features - -* **Deploy Anywhere You Have Windows**/**Cloud Ready** (except Nano, sorry little buddy!). Yes, that includes Server.Core and [Windows Docker Containers](https://github.com/Microsoft/vsts-agent-docker/blob/f870fbf259a803c6a6d902e1c01f631936069d66/windows/servercore/10.0.14393/standard/VS2017/Dockerfile). [Any supported version of Windows](xref:chocolatey-components-dependencies-and-support-lifecycle#supported-windows-versions). Requires [any supported version of PowerShell](xref:chocolatey-components-dependencies-and-support-lifecycle#supported-powershell-versions) and Microsoft .NET Framework 4.x+. You can deploy on-prem, to Azure, AWS, or any cloud provider you might be looking at. -* **Deploy with Everything.** Anything that can manage endpoints or do remote deployments can either direct Chocolatey through commands, batches, or scripts. Full configuration management solutions like Ansible, Chef, PowerShell DSC, Puppet or Salt typically have providers/modules that allow you to work within their languages to manage both Chocolatey installation/configuration and software. -* **All Software Is a First Class Citizen.** You know how for most things, they only manage/report on the things installed in Add/Remove Programs (Programs and Features)? We count it all, because Windows software is more than just installers, and they all have security findings. So deploy your installers, your scripts, zips, runtime binaries, and yes, internal software all with one simple solution. Then lean on the reporting and inventory to be aware of all aspects of software you are managing. -* **Packages are Independent and Portable.** When you deploy through multiple systems or want to migrate from one to another, you can take the work you've done with Chocolatey with you. How is that for some major time-savings? -* **Test Your Deployments.** When's the last time you tested that deployment script you wrote for SCCM? Write it as a Chocolatey package instead and then you can test your infrastructure to be more comfortable when you push that change out to your constituents. -* **Completely Offline and Secure.** Chocolatey has zero call home, requires no network access to use (although we recommend for ease of management, you at least have internal network access!). Chocolatey does come with a default source that is the community repository. Turn that off and set up your own sources (FOR FREE). See our [guide on organizational use](xref:organizational-deployment-guide) to get started (it even has scripts!). -* **Create Your Own Deployment Packages** (FOR FREE) and, get this, **use them internally** (FOR FREE). Get started as simply as `choco new ` and then check out the "just in time" documentation interweaved right into the output! -* **PowerShell Automation.** You know those little scripts you've been writing for software deployments for years? Welcome to a breath of fresh air, you are going to love Chocolatey! -* **Manage Dependencies With Ease.** You ever have a very complex, specific installation order? It becomes suddenly very easy when you are using a package manager like Chocolatey. Then you can concentrate on harder problems, like what flavor to add to your coffee today. -* **Open Source Licensing Is Ready for Business.** We have [Apache v2 licensing](https://github.com/chocolatey/choco/blob/master/LICENSE), no special restrictions need apply. Our commercial options come with a more business friendly [Software License agreement](https://chocolatey.org/support#business-legal) (and yes, we do have a redline format). -* **Commercial Options Add Support + AMAZING Features.** Our top of the line [Chocolatey for Business (C4B) edition](https://chocolatey.org/compare#compare) includes over 20+ features that take Chocolatey to the next level and make it a full software management solution and not just a package manager. Go ahead, right click on an installer and create a fully unattended software deployment in 5 seconds! If you have any issues, our support team is ready and waiting to help you move forward. -* **Customers Help Define Our Work.** We determine and prioritize our work based on where customers want things to go. We are building a platform, and we are working with you to make it better. -* **Security Is Our Focus.** Take a stroll through our [security page](xref:security). With everything we design, we focus on simplicity, scalability, and security. -* **Bridge the Gap.** Have you started to look at moving from those legacy automation systems to something more modern like Ansible, Puppet, or Chef and didn't know where to start? Start shifting the software management over to Chocolatey and taking those existing infrastructure/end point management tools back to just the remote deployment. Then when you are ready, you shift over to those modern automation solutions without needing to rewrite everything! Those Chocolatey packages work with all systems! -* **Scale With Ease.** There are massive deployments of Chocolatey, even the open source edition, in large enterprises. Chocolatey is deployed in everything from small startups all the way up to those fortune 500 companies. - -### Common Thoughts - -**"Some of the software I manage is extremely complex and difficult to install."** You mean like [Office](https://community.chocolatey.org/packages/Office365ProPlus), [SQL Server](https://github.com/DarwinJS/ChocolateyDesignPatterns/tree/af7896893de95bdd5c3c430a8cf7a1b6aa8f0983/mssqlserver-standard), or Oracle? How about MatLab? AutoCAD? All can be more easily managed with Chocolatey. Stop torturing yourself, give Chocolatey a shot. Trust us, you'll never go back to those earlier methods. Come into modern software management and automation. It's available, and it's for Windows!! - -**"I deal with software installers that don't install silently."** There are solutions for those badly behaved installers. If your team doesn't have the skillset for something like MSI repackaging, you can lean on our packaging support team that can whip those badly behaved installers into shape for a low cost (provided you are using a commerical edition of Chocolatey). - -**"But I'm not a developer, why should I learn PowerShell?"** Okay, time for some serious talk. If you are not learning better automation now, your peers are. They are going to move into this modern automation (DevOps as some might call it) and you might end up asking folks if they "want fries with that?". We are professionals that typically can call for higher salaries - that means we need to continue to provide value for the organizations that employ us. If we are not already familiar, we should learn to work with automation (PowerShell) and some basic foundational concepts of development (like source control). It's not hard, you might find it addictive. - -**"I like GUIs or my coworkers like GUIs."** We understand that aspect, that's why [our business edition offering](https://chocolatey.org/compare#compare) employs many more visual interfaces. - -### Summary - -All we're saying is, it's time to step out of the dark ages and stop either doing things manually or stop killing yourself trying to work directly with those complex systems. Rub a little Chocolatey on them, stop powering through extra work at night, and go home to see your family in the evening because you use modern software automation and tools. Have confidence in your deployments and get the right information back to fix quickly when things go wrong. Chocolatey has been around for nearly ten years, thousands of companies and hundreds of thousands of people use it. Lean on a solution that has been proven to work over and over again. It will change your life, it may even get you a raise! You will get more done in the same amount of time, and your employer will take notice. Windows deserves better automation and so do you. - -### Already familiar with other package managers? - -Chocolatey is like dpkg (Apt-Get)/RPM, but built with Windows in mind (there are differences and limitations). It can also do configuration tasks and anything that you can do with PowerShell. Another notable difference, it is really easy to create and maintain packages compared to those older, existing solutions for POSIX. - -Chocolatey manages packages (strictly nupkg files) and those packages manage software (could be installers, could be runtime binaries, could be zips or scripts). - -> Chocolatey is a software management tool that is also a package manager. It functions fantastically well when the runtime software is all included in the package and it doesn't make use of native installers. However to approach the Windows ecosystem a package manager also needs to know how to manage actual software installations, thus why Chocolatey does that as well. For publicly available packages, copyright keeps from having binaries embedded in packages, so Chocolatey is able to download from distribution points and checksum those binaries. - -## Requirements - -### Chocolatey Clients - -With Chocolatey clients, we ensure that Chocolatey is going to run with low memory footprints because you will have all aspects of things you will need to manage and different space and memory available across all of those clients. Chocolatey has a very wide reach into where it can be installed. - -For Chocolatey CLI clients, you will need to [set up the requirements](xref:setup-choco#requirements). - -#### Chocolatey Components - -* Chocolatey CLI aka choco (or choco.exe) is a client (not a Windows service) that provides the core of Chocolatey and the installation store for locally installed packages. This is important as Chocolatey manages packages, not Programs and Features directly - Programs and Features is limited only to software that has "installers" and Chocolatey treats all aspects of Windows software as first class citizens (zips, scripts, binaries, installers), thus it needs to track and manage those things separately. -* Chocolatey GUI is an application that runs when a user runs it (also not a Windows Service). -* Chocolatey Agent (aka chocolatey-agent) is a Windows service available in Chocolatey for Business. It is used for [Self-Service Installation](xref:self-service-anywhere) and Chocolatey Central Management. - -#### Space Requirements - -* Chocolatey CLI has an impact of 15 MB on default install plus the space the installed packages use up. -* Chocolatey GUI takes up another 50-100 MB of space on default installation. -* Chocolatey Agent (aka chocolatey-agent) is a Windows service available in Chocolatey for Business - it has an impact of about 10 MB. - -**RECOMMENDATION**: We recommend enough free space for the applications you will install plus another 1 GB for allowing Chocolatey to process that. You will want to turn on Package Reducer (commercial editions) if you have it to really reduce the impact of embedded packages, which bring reliability but also increase footprint (unless you have Package Reducer). If you don't have Package Reducer and you are embedding binaries into nupkgs, you will need 3 times the space of what you are installing unless you explicitly clean up the extracted installers/zips in your automated scripts - then you will need 2x the space when considering the nupkg will still contain embedded binaries (and the nupkg must stick around). Unfortunately, this is going to be a calculation to understand exact space requirements and it really depends on what you will install. - -#### Memory Requirements - -* Chocolatey CLI only runs when called. It falls into managed memory thus can work in environments with low amounts of memory provided that they have enough memory available to manage software installations. -* Chocolatey GUI only runs when the application is open and is also in managed memory. It can work on systems with low amounts of memory. -* Chocolatey Agent (aka chocolatey-agent) - it is always running but has a very low footprint unless it is processing something. - -**RECOMMENDATION**: At least 2GB of RAM at a bare minimum, but recommend at least 8GB for managing installations. - -### Chocolatey Repository Servers - -Unforunately it's harder to make recommendations here as it is really dependent on the repository that you choose and what requirements they have. It varies from a Windows deployment to Linux deployed repositories, from Java-based, to .NET-based, to PHP, and Rust-based repositories. The requirements vary wildly, plus you may use those repositories that address multiple types of packages and would need to figure out the space available for that. - -**SPACE RECOMMENDATION**: Have enough space for 10x the size of the installers and other software you will store. This will allow for some default growth. We would recommend 100 GB at a minimum. - -We've compiled a list of requirements for [commercial repository options](xref:host-packages#commercial-repository-system-requirements). Chocolatey Simple Server (Chocolatey.Server) can be put on really minimum hardware that could be 1-2GB of RAM, low CPU, and as little as 5 GB of space (number of packages you store will drive this). You will just want the network transfer to be fast. - -### Chocolatey Central Management - -Requirements coming soon. Just imagine normal recommendations for an ASP.NET IIS deployment, a SQL Server back end, and 1+ Windows Services (depending on scale). - -## Using Chocolatey - -Now that you have Chocolatey on your machine ([need to install?](xref:setup-choco)), you can run several commands. - -Take a look at the [command reference](xref:choco-commands). We are going to be using the [install command](xref:choco-command-install). - -Let's install [Notepad++](https://notepad-plus-plus.org/). - -1. Open a command line as an administrator. -1. Type `choco install notepadplusplus` and press Enter. -1. That's it. Pretty simple but powerful little concept! - -### Overriding default install directory or other advanced install concepts - -1. Yes we support that through the use of install arguments - see [Install Arguments](xref:choco-command-install#installarguments) -1. If you wanted to pass native argument to the installer, like the install directory, you would need to know the silent argument passed to that particular installer and then you would specify it on the command line or in the packages.config. -1. If it was an MSI, then usually you could pass `-ia "INSTALLDIR=""D:\Program Files"""` (for cmd.exe, it's different for PowerShell). See [how to pass options/switches](xref:choco-commands#how-to-pass-options-switches) for specifics on passing quoted values through. -1. For example, Notepad++ uses the [NSIS](https://nsis.sourceforge.io/Main_Page) (NullSoft Scriptable Install System) installer. If we look at the silent options, we see that [/D](https://nsis.sourceforge.io/Docs/Chapter3.html#installerusagecommon) is how we influence the install directory. So we would pass `choco install notepadplusplus.install -ia "'/D=E:\SomeDirectory\somebody\npp'"` -note that we are looking at the specific package over the virtual (although you can do the same with notepadplusplus as well). - -Is there a better way? Absolutely, see [ubiquitous install directory switch](xref:install-directory-override)! - -## Terminology - -Software and Package are not terms used interchangeably in the Chocolatey community. It's important to understand the distinction between them and how they are related. - -* **Chocolatey** - Windows package manager for software management, can also be considered a framework -* **Chocolatey.org** - Website that is one stop shop for Chocolatey information and contains a community maintained package repository. It is important to understand that Chocolatey and the community feed are not intertwined, they are not the same thing. See [community feed disclaimer](xref:community-packages-disclaimer) to get a better understanding. -* **NuGet** - Framework and .NET package manager for software libraries. Chocolatey uses the NuGet packaging framework -* **Package** - See [What are Chocolatey Packages?](#what-are-chocolatey-packages). Packages can contain the software they represent and the final location of software may or may not be in the package. -* **Software** - Software refers to the actual runtime software that a package represents. This can be installed to the system through native installers, or come from zip/archive files or just dropping the runtime software right into the package. -* **Native Installer** - Actual installers that install software into Programs and Features, "natively" on a Windows machine. This is like MSI, InnoSetup (exe), NSIS (exe), InstallShield (exe/msi), etc. Windows has over 20 different installer formats. -* **Install Package** - packages that wrap native installers -* **Portable Package** - packages that use zip or just contain the runtime software. Usually these packages do not require administrative privileges to install or run. See [Portable application](xref:faqs#portable-application-something-that-doesnt-require-a-system-install-to-use) -* **Extension Package** - packages that provide extensions to Chocolatey's PowerShell module through additional PowerShell modules. -* **Template Package** - packages that have packaging templates in them, used in package creation. See [create your own package templates](xref:create-custom-package-templates). -* **Metapackage** - packages that only exist to take dependencies on other packages, usually as a way of providing one command to get a complete setup. Some metapackages exist to provide discoverability, such as "git" versus 'git.install." The git package just depends on git.install, so running the install for either package will result in the git software being installed on the machine. -* **Virtual package** - a concept that a package can "provide" some functionality and any package that meets that provides will be considered a dependency met. For example, if you need to take a dependency on a pdf reader, you wouldn't want to take a hard dependency on AdobeReader, but instead you would hope that adobereader provides pdf as well as other packages like SumatraPDF and FoxitReader. Then you could take a dependency on pdf and if any of those packages are installed, the dependency is met. Otherwise an algorithm would determine which one to install. THIS IS NOT IMPLEMENTED AT THIS TIME WITH CHOCOLATEY. - -## What Are Chocolatey Packages? - -Chocolatey packages are known as nupkg files, which is a compiled NuSpec or a fancy zip file that knows about package metadata (including dependencies and versioning). These packages are an enhanced NuGet package, they have additional metadata that is specific to Chocolatey. Chocolatey is also compatible with vanilla NuGet packages. A Chocolatey package can contain embedded software and/or automation scripts. - -Chocolatey packages are not just something fancy on top of MSI/Exe installers. Chocolatey definitely supports that avenue and, with the addition of unzipping archives, it is the most widely used aspect of Chocolatey, especially when you see the packages on the community feed (https://community.chocolatey.org/packages aka dot org). Chocolatey is about managing packages, and it works best when those packages contain all of the software instead of reaching out to external/internet resources for the software those packages represent. When you look at the community feed, you are seeing one representation of the way you can build packages, mostly driven by [distribution rights](xref:legal#distributions) that govern when packages can redistribute software or not. Those distribution rules do not govern private/internal packages, so the rules are a bit different. Packages internal to organizations are wide open to do quite a bit more. You can do software embedded packages where executables are automatically added to the path (shimmed) and/or PowerShell automation scripts to do pretty much anything, including running native installers that may be embedded or downloaded as part of the automation script (again, one of the most widely seen aspects on dot org). - -Packages with everything embedded are much more deterministic and repeatable, things most businesses require. You just won't see that as often on the community feed due to the aforementioned [distribution rights](xref:legal#distributions). - -The closer the underlying software a package represents is to the package (as in executables and files included in the package), the more Chocolatey behaves like a package manager. - -## How does Chocolatey work? - -How the heck does this all work? - -### Installation - -1. Chocolatey uses NuGet (NuGet.Core.dll) to retrieve the package from the source. This is typically a nupkg that is stored in a folder, share, or an OData location (HTTP/HTTPS). For more information on sources, please see [Sources](xref:choco-command-sources) and [Source Repositories](xref:host-packages). -2. The package is installed into `$env:ChocolateyInstall\lib\`. The package install location is not configurable - the package must install here for tracking, upgrade, and uninstall purposes. The software that may be installed later during this process **is** configurable. See [Terminology](#terminology) to understand the difference between "package" and "software" as the terms relate to Chocolatey. -3. Choco determines if it is self-contained or has automation scripts - PowerShell scripts (*.ps1 files) and possibly other formats at a later date. -4. Choco takes a registry snapshot for later comparison. -5. If there are automation scripts, Chocolatey CLI will run those. They can contain whatever you need to do, if they are PowerShell you have the full power of Posh (PowerShell), but you should try to ensure they are compatible with the [supported PowerShell versions](xref:chocolatey-components-dependencies-and-support-lifecycle#supported-powershell-versions). -6. Choco compares the snapshot and determines uninstaller information and saves that to a .registry file. -7. Choco snapshots the folder based on all files that are currently in the package directory. -8. Choco looks for executable files in the package folder and generates shims into the `$env:ChocolateyInstall\bin` folder so those items are available on the path. Those could have been embedded into the package or brought down from somewhere (internet, ftp, file folder share, etc) and placed there. If there is a shim ignore file `.exe.ignore`, then Chocolatey will not generate a shim in the bin folder. - -### Upgrade - -1. Starting in 0.9.10, Chocolatey will look for and run a chocolateyBeforeModify.ps1 file in the existing package prior to upgrading or uninstalling a package. This is your opportunity to shut down services and/or processes. This is run from the existing package, not the new version of the package. If it fails, it just passes a warning and continues on. -2. Similar to install, except choco will make a backup of the package folder (and only the package folder) prior to attempting upgrade. -3. The files snapshot is used to determine what files can be removed from the package folder. If those files have not changed, they will be removed. -4. If the upgrade fails, choco will ask if you want to rollback the package folder to the previous version. If you choose to move roll back, it will put the backed up package directory back in place. This does not fix any folders you may have been using outside of the package directory, such as where the native installer may have installed a program to nor the location of `Get-ToolsLocation` (e.g. `c:\tools`). You will need to handle those fixes on your own. Chocolatey also doesn't rerun any install scripts on rollback. - -### Uninstall - -1. Choco makes the determination that the package is actually installed. -2. Starting in 0.9.10, Chocolatey will look for and run a chocolateyBeforeModify.ps1 file in the existing package prior to upgrading or uninstalling a package. This is your opportunity to shut down services and/or processes. If it fails, it just passes a warning and continues on. -3. Choco will make a backup of the package folder. -4. The automation script is run if found. This should be used to clean up anything that is put there with the install script. -5. If auto uninstaller is turned on, choco will attempt to run the auto uninstaller if a silent uninstall can be determined. Otherwise it will prompt the user (unless -y) to ask if they want the uninstaller to continue. The auto uninstaller can automatically detect about 80% of the different native uninstallers and determine or use the silent uninstall arguments. -6. If everything is successful so far, the files snapshot is used to determine what files can be removed from the package folder. If those files have not changed, they will be removed. -7. If everything is deleted from the package folder, the folder is also removed. - -When a package has an exe file, Chocolatey will create a link "shortcut" to the file (called a shim) so that you can run that tool anywhere on the machine. See [shimming](xref:shim) for more information. -When a package has a chocolateyInstall.ps1, it will run the script. The instructions in the file can be anything. This is limited only by the .NET framework and PowerShell. -Most of the Chocolatey packages that take advantage of the PowerShell download an application installer and execute it silently. - -## Where are Chocolatey packages installed to? - -Chocolatey packages are installed to `ChocolateyInstall\lib`, but the software could go to various locations, depending on how the package maintainer created the package. - -Some packages are installed under `ChocolateyInstall\lib`, others - especially packages that are based on Windows installers (.msi files) - install to the default path of the original installer (which is most likely within `Program Files`). - -There are also packages for which you can set a custom installation path. These packages (like ruby) use the `$env:ChocolateyBinRoot` environment variable. If this variable does not exist, it will be created as `c:\tools` e.g. `C:\tools\ruby193`. To change this behavior, you can set `$env:ChocolateyBinRoot` to an existing folder, e. g. `C:\somestuff`. Packages that use the environment variable, will then be installed in the given subfolder, f. ex. `C:\somestuff\ruby193`. - -## How does Chocolatey work with Programs and Features? Existing installs? - -Many packages use native software installers, so Chocolatey allows the installer itself to handle install/upgrade/uninstall scenarios. This means it can work directly with already installed software just by using `choco install` to make Chocolatey aware of existing software. You can also use a specially crafted install command (skip powershell) to allow choco to install a package without installing the already installed native software. - -## Where does Chocolatey install packages from? - -By default it installs packages from community.chocolatey.org (the community feed). But you can change this by adding default sources and/or using the `--source` switch when running a command. - -When you [host internal packages](xref:host-packages), those packages can embed software and/or point to internal shares. You are not subject to software distribution rights like the packages on the community feed, so you can [create packages](xref:create-packages) that are more reliable and secure. See [What are Chocolatey Packages](#what-are-chocolatey-packages) for more details. diff --git a/input/en-us/guides/create/create-cli-package.md b/input/en-us/guides/create/create-cli-package.md deleted file mode 100644 index 6869808bcd..0000000000 --- a/input/en-us/guides/create/create-cli-package.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -Order: 4 -xref: howto-create-cli-package -Title: How To Create a CLI Executable Package -Description: A walkthrough creating a package containing a CLI executable application ---- - -Chocolatey packages can also just contain executables - and you won't even need to write an installation script to use them! We're going to walk you through creating a CLI executable package now - assuming you've already run through [Preparing Your Environment for Package Creation](xref:howto-prepare-env). - -### What Is a CLI Executable - -We'd class just about any executable (or EXE file) that can be run without installation as a CLI executable, and developers of software projects will sometimes publish a separate version of software available to just download and run rather than install. - -### Why Might You Use an Executable Package - -These packages can be very helpful for users who want to have tools quickly available without installation - sometimes referred to on the Chocolatey Community Repository as portable packages. - -They're generally extremely quick to install, as there's no additional logic being run, and leave little to no footprint on the computer after removal. - -This can be very helpful on a build container, or for tools that just don't need to be installed. - -### Using Shimgen - -Normally, we'd talk about a function included with Chocolatey CLI that allows us to install some files - in this case, we're just dropping an EXE onto disk (and in the package directory, at that) - how is this going to work? Nobody will want to find and use the entire path to the tool every time! Happily, this has been solved for a while: - -[`Shimgen.exe`](xref:shim) is a long-term feature included with Chocolatey CLI, and is used so that you can have items available on the `PATH` (allowing them to be run on the command-line) without adding a new entry to the `PATH` for every package that needs it. - -EXEs that are found within the package directories at the end of installation have a shim created in the `$env:ChocolateyInstall\bin` folder, which is on the `PATH`. - -If you have an EXE file within your package that you don't want to have shimmed, you should create an empty file named `.ignore` in the same directory as the EXE will be found. - -You can find more details around uses for Shimgen on [the docs page](xref:shim#faq). - -#### Creating a CLI Executable Package - -In this example, we will create a package that contains `gh.exe`, the GitHub CLI executable. - -> :choco-info: For this example, we'll provide URLs that are based on versioned URL that worked at the time of writing. -> These were found in the [GitHub releases](https://github.com/cli/cli/releases) for the tool. - -#### Creating Package Structure - -This package type is very simple, mostly needing the EXE itself, and a package metadata file - often referred to as the `.nuspec`. - -1. In your `tutorials` folder, create a new folder for this package. For the example, we will call it `gh.portable`. -1. Within this folder, create `gh.portable.nuspec`, with the content as [shown below](#package-metadata-content). -1. Navigate to the [GH GitHub Releases](https://github.com/cli/cli/releases/) page, and download the latest version of `GitHub CLI windows amd64` (e.g. `GitHub CLI 2.39.2 windows amd64.zip` - you may need to click `Show all releases` to find it). - a. This will be a zip file so, after the download has completed, extract it directly into the package directory. - -##### Package Metadata Content - -```xml - - - - - gh.portable - $version$ - __REPLACE_YOUR_NAME__ - GitHub CLI (Portable) - GitHub - https://cli.github.com/ - https://github.com/cli/cli/blob/trunk/LICENSE - https://github.com/cli/cli/ - https://github.com/cli/cli/issues - gh cli portable example - GitHub on the Command Line - https://github.com/cli/cli/releases - - - - - - -``` - -You'll want to update the following fields in the `metadata` section: - -* **owners**: This field shows who maintains the package - your name or handle should be added! - -We have already filled many of the other included fields, including the following: - -* **id**: We have chosen the example package name, including the `.portable` suffix - which is often used to denote non-install packages on the Chocolatey Community Repository. -* **version**: We have used `$version$` here, as we're going to introduce a neat trick later to update this during `choco pack`. -* **files**: We have added paths matching the files within the release artifact you downloaded above in order to pack the extracted files correctly. - -### Compiling Your Package - -You can now run `choco pack` to compile your Chocolatey package, creating a file with a `.nupkg` extension, ready for installation! - -1. In VS Code, press `Ctrl+Shift+ P` or use the **View** menu and click on **Command Palette**. -1. Select `Chocolatey: Package Chocolatey package(s)` from the prompt. -1. Select `gh.portable.nuspec` from the prompt. -1. Add `--version 2.39.1` (or the most recent version), which will override the version in the metadata, and press **Enter**. - -You should have a new package generated in your root directory. - -### Installing Your Package - -You can now test installation of the package. - -> :choco-warning: **Beware** that installing and uninstalling the example package may affect existing installations (as you're essentially testing in production). We recommend testing on a separate environment that is not crucial to your workflow. - -In an _elevated PowerShell command prompt_, run the following: - -```PowerShell -choco install gh.portable --source='tutorials' -y -``` - -The command should run, and `gh.exe` should now be available on the command line. You should be able to run it: - -```PowerShell -# Should produce output -gh.exe --version - -# Should show the path to the shim, within chocolatey/bin -Get-Command gh.exe -``` - -### Uninstalling Your Package - -Similarly, you should be able to test the uninstall. - -```PowerShell -choco uninstall gh.portable -y -``` - -The same tests shown above should now show an error, and no command found. - -### Conclusion - -You should now have a grasp of the potential for portable / CLI packages! Congratulations. Have fun, and try creating your own! \ No newline at end of file diff --git a/input/en-us/guides/create/create-config-package.md b/input/en-us/guides/create/create-config-package.md deleted file mode 100644 index e6e5b5d4f1..0000000000 --- a/input/en-us/guides/create/create-config-package.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -Order: 6 -xref: howto-create-config-package -Title: How To Create a Configuration Package -Description: A walkthrough creating a package that configures your computer ---- - -Some people are surprised when they learn that Chocolatey packages don't always install software. - -Sometimes, you may want to apply configuration to software you've installed. Sometimes, you just need to drop a file into the right place. - -In this how-to, we'll talk about how to make a package that doesn't install anything - and just applies configuration. - -### What Is a Configuration Package - -A configuration package, predictably, applies configuration during the installation stage. You can also use this sort of package to drop files into the right place. - -### Why Would I Want To Use One? - -An example of a basic configuration package would be a package that drops a license file to the right location on a computer, or a package that configures a web-server with some known values that you want to be used across a set of computers. - -We actually suggest something like this for Chocolatey for Business customers to ensure their Chocolatey licenses are in-date and easily maintained! - -### Using `Copy-Item` (and Friends) - -A lot of package types have Chocolatey helper-functions ready to be used. However, configuration and file-distributing packages don't have specific functions shipped for the purpose. - -We'll be using built-in PowerShell functions and cmdlets instead, such as `Copy-Item`. - -#### Creating a Configuration Package - -In this example, we're going to create an example package to license and configure an example application, helpfully titled `exampleapp`. - -We can run `choco new` to create a basic package, and then remove everything we don't need: - -1. Open your `tutorials` folder in VSCode. -1. Press **Ctrl+Shift+P** or use the **View** menu and click on **Command Palette**. -1. Select `Chocolatey: Create new Chocolatey package`. -1. Give your package a name, e.g. `example-config`. -1. Select the default template, and press **Enter**. - -This should result in a new directory, containing the following files: - -```text -example-config -├── tools -│ ├── chocolateyBeforeModify.ps1 -│ ├── chocolateyInstall.ps1 -│ ├── chocolateyUninstall.ps1 -│ ├── LICENSE.txt -│ ├── VERIFICATION.txt -├── example-config.nuspec -├── ReadMe.md -``` - -Delete the `chocolateyBeforeModify.ps1`, `VERIFICATION.txt`, and `ReadMe.md` files from the folder structure. - -You'll want to open the `example-config.nuspec` file, and fill out the following fields in the `metadata` section if required: - -* **packageSourceUrl**: This can be removed, or updated with your source URL. -* **owners**: This field shows who maintains the package - your name or username is appropriate! -* **authors**: The authors of the software in question - this should be updated with your name or username. -* **projectUrl**: The URL of the software in question - for this example package, this should be removed. -* **tags**: Tags for the repository you're publishing the package to. These can be updated however you prefer, though the Chocolatey Community Repository has some guidance on what is needed there. -* **summary**: This is a summary of the package contents. For this example, you could add that this package will license and configure your example software. -* **description**: This is a description of the package contents, and generally contains more detail than the summary - including things like package parameters. It supports markdown. We won't be dealing with anything that complex here! - -You can now fill or remove any other commented out sections of the `example-config.nuspec` file, if you want. Your file should end up looking something like this: - -```xml - - - - - example-config - 0.1.0 - Example Configuration - PackageMaintainer - example config-only - A package that configures 'example' - Further detail about the configuration that is applied, and any package parameters. - - - - - -``` - -#### Creating Your Install Script - -Install may be a bit of a misnomer, here, but as the script that runs when the package is "installed" is called `chocolateyInstall.ps1`, it seems appropriate. - -The new package you have created will already have an install script in the `tools` directory. - -You can remove the contents of the script, as it's the familiar template - and we won't be installing anything. - -Instead, replace it with some sample content for our planned configuration: - -```PowerShell -$ErrorActionPreference = 'Stop' -$ToolsDir = Split-Path $MyInvocation.MyCommand.Definition -Parent - -$ConfigDirectory = "C:\ProgramData\exampleapp\" - -# Ensure the license directory exists -if (-not (Test-Path $ConfigDirectory)) { - $null = New-Item $ConfigDirectory -ItemType Directory -} - -# Copy the license to the correct path -Copy-Item -Path (Join-Path $ToolsDir "LICENSE.txt") -Destination $ConfigDirectory - -# Backup the existing Configuration file, if it exists -$ConfigFile = Join-Path $ConfigDirectory "config.json" -if (Test-Path $ConfigFile) { - Copy-Item $ConfigFile -Destination "$ConfigFile.backup" -} - -# Write Configuration File -@{ - LicensePath = Join-Path $ConfigDirectory "LICENSE.txt" - ComputerName = $env:ComputerName -} | ConvertTo-Json | Set-Content $ConfigFile -``` - -#### Considering Uninstallation - -There's no automatic procedure for uninstalling configuration. In this case, you can add an uninstall script that rolls back your changes. - -If you wanted to do this, you would overwrite the contents of the `chocolateyUninstall.ps1` script with something like this: - -```PowerShell -$ConfigDirectory = "C:\ProgramData\exampleapp\" -$LicensePath = Join-Path $ConfigDirectory "LICENSE.txt" -$ConfigPath = Join-Path $ConfigDirectory "config.json" - -# Remove the license flie if it exists -if (Test-Path $LicensePath) { - Remove-Item $LicensePath -} - -# Remove the config file if it exists -if (Test-Path $ConfigPath) { - Remove-Item $ConfigPath -} - -# And restore the backup, if it exists -if (Test-Path "$ConfigPath.backup") { - Move-Item "$ConfigPath.backup" -Destination $ConfigPath -} - -# Clean up the config directory, if it's empty -if (-not (Get-ChildItem $ConfigDirectory)) { - Remove-Item $ConfigDirectory -} -``` - -> :choco-warning: Please note that this uninstall script is quite naive, as you would need to consider updated backups and what state you would want to restore to. - -### Compiling Your Package - -You can now run `choco pack` to compile your Chocolatey package, creating a file with a `.nupkg` extension, ready for installation! - -1. In VSCode, press **Ctrl+Shift+P** or use the **View** menu and click on **Command Palette**. -1. Select `Chocolatey: Package Chocolatey package(s)` from the prompt. -1. Select `example-config.nuspec` from the prompt. -1. Press **Enter**, providing no additional input. - -You should have a new package generated in your current working directory. - -### Installing Your Package - -You can now test installation of your package. - -In many cases, we would recommend testing on a dedicated test system that will not be affected by a package being installed - but as this package is entirely made up, there is nearly no consequence of installing and uninstalling it (assuming you don't have an application called `exampleapp` that stores data in the way we've used, here). - -In an _elevated PowerShell command prompt_, run the following: - -```PowerShell -choco install example-config --source='tutorials' -y -``` - -The command should run, and opening the `C:\ProgramData\exampleapp` directory should show your license and config file. - -### Uninstalling Your Package - -If you did update the uninstall script, you should be able to run `choco uninstall`: - -```PowerShell -choco uninstall example-config -y -``` - -The package should be uninstalled successfully, and checking `ProgramData` should show that the `exampleapp` directory (and the contained files) should have been removed. - -### Conclusion - -At this point, you should have a package that licenses and configures an (imaginary) application! Congratulations! Hopefully the lessons here can be applied to your more specific applications. \ No newline at end of file diff --git a/input/en-us/guides/create/create-custom-package-templates.md b/input/en-us/guides/create/create-custom-package-templates.md deleted file mode 100644 index 66b643b272..0000000000 --- a/input/en-us/guides/create/create-custom-package-templates.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -Order: 40 -xref: create-custom-package-templates -Title: Create Custom Package Templates -Description: How to create custom package templates -RedirectFrom: docs/how-to-create-custom-package-templates ---- - -As of [choco 0.9.9.9](https://github.com/chocolatey/choco/issues/76), you can create your own custom package templates when the built-in template is not enough. - -## Overview - -A template is used for creating packages. Chocolatey (choco) has a built-in template that it uses when generating a new package from the command [`choco new`](xref:choco-command-new). - -### Where do Templates go? - -If you drop a template into `$env:ChocolateyInstall\templates` folder, you can use `-t name_of_template` to generate a choco template based on that. So for: - -![Windows Explorer showing the installation location for a new template with the name of Organization](/assets/images/features/choco-templates-location.png) - -You would call `choco new pkgname -t organization` and choco will use the template folder instead of the built-in template. - -### Can I replace the built-in template? - -If you are using a version of Chocolatey CLI earlier than 0.12.0, you can replace the built-in template by copying the template to a folder called `default`. The `choco new` command will then use that by default. - -Chocolatey CLI version 0.12.0 or later introduced the [`choco template` command](xref:choco-command-template). You can use it to list the installed templates and [set the `defaultTemplateName`](xref:configuration#general) to set the template to be used by default when running the `choco new` command. You can also still copy the template files that worked with previous versions. - -### What values can I template? - -You can get the names by running `choco new -h`: - -~~~ -Possible properties to pass: - packageversion - maintainername - maintainerrepo - installertype - url - url64 - silentargs -~~~ - -However `PackageName` and `PackageNameLower` also show up as they are based on the name of the package that you pass e.g. "bob" in `choco new bob` - -Then you surround those templated values with `[[]]` to make them templated for choco to use. - -> :choco-info: **NOTE** -> -> You can set and pass arbitrary values through as well. This is shown in the example with `CustomValue`. - -## Template Example - -This is a template for embedding an MSI into a package. This removes almost everything that is unnecessary for embedding software into packages. And because the autoUninstaller handles MSIs without an issue, we don't need a chocolateyUninstall.ps1. - -A file with the extension `.nuspec`: - -~~~xml - - - - [[PackageNameLower]] - [[PackageName]] (Install) - [[PackageVersion]] - Original authors - [[MaintainerName]] - __REPLACE__MarkDown_Okay [[AutomaticPackageNotesNuspec]] - - [[PackageNameLower]] admin - - - - - - -~~~ - -> :choco-info: **NOTE** -> -> Ensure that the template nuspec is encoded as UTF8 with BOM to avoid issues with non-ascii characters. The final package source generated by the template will contain the correct nuspec without a BOM. - -`tools\chocolateyInstall.ps1`: - -~~~powershell -# Custom value: [[CustomValue]] -$ErrorActionPreference = 'Stop'; # stop on all errors - -[[AutomaticPackageNotesInstaller]] -$packageName = '[[PackageName]]' -$toolsDir = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)" -$fileLocation = Join-Path $toolsDir 'NAME_OF_EMBEDDED_INSTALLER_FILE' - -$packageArgs = @{ - packageName = $packageName - file = $fileLocation - fileType = '[[InstallerType]]' #only one of these: exe, msi, msu - - #MSI - silentArgs = "/qn /norestart /l*v `"$env:TEMP\chocolatey\$($packageName)\$($packageName).MsiInstall.log`"" - validExitCodes= @(0, 3010, 1641) - #OTHERS - #silentArgs ='[[SilentArgs]]' # /s /S /q /Q /quiet /silent /SILENT /VERYSILENT -s - try any of these to get the silent installer - #validExitCodes= @(0) #please insert other valid exit codes here -} - -Install-ChocolateyInstallPackage @packageArgs -~~~ - -Once installed, call this with `choco new test -t