# Core Modules

## file\_edit:

```yaml
  - name: Edit a configuration file  
    file_edit:
      path: /etc/vsftpd.conf  # Path to the remote file
      search: listen=NO  # Search pattern
      replace: listen=YES
      mode: "0640"
      group: sharif
      user: sharif
```

* **`name`**`: Edit a configuration file` is a user-friendly name for the task, describing what it does.
* **`file_edit`** is the opsshell module used for editing files.
  * **`path`**`: /etc/vsftpd.conf` specifies the path to the remote file that you want to edit. In this case, it's `/etc/vsftpd.conf`.
  * **`search`**`: listen=NO` is the search pattern that Opsshell will look for in the file. It's searching for the text `listen=NO` within the file.
  * **`replace`**`: listen=YES` is the text that will replace the matched search pattern. In this case, it's replacing `listen=NO` with `listen=YES`.
  * **`mode`**`: "0640"` sets the file permissions (mode) of the edited file. In this case, it's setting the file permissions to be 0640.
  * **`group`**`: sharif` specifies the group ownership of the edited file. The group is set to "sharif."
  * **`user`**`: sharif` specifies the user ownership of the edited file. The user is set to "sharif."

This task will edit the `/etc/vsftpd.conf` file on the remote server by replacing occurrences of `listen=NO` with `listen=YES`. It will also change the file permissions to 0640 and set the ownership to the "sharif" group and user.

## file\_dir:

```yaml
  - name: Create directory and file
    file_dir:
      path: /home/sharif/infolytx
      state: directory
      mode: "0640"
      group: sharif
      user: sharif
```

* **`name`**`: Create directory and file` is a user-friendly name for the task, describing its purpose.
* **`file_dir`** is the Opsshell module used for managing directories and files.
  * **`path`**`: /home/sharif/opsshell` specifies the path for the directory you want to create. In this case, it's `/home/sharif/opsshell`.
  * **`state`**`: directory, file` indicates that you want to create a directory and file. If the specified path already exists as a file, it will be replaced with a directory.
  * **`mode`**`: "0640"` sets the permissions (mode) for the directory. In this case, it's setting the permissions to be 0640.
  * **`group`**`: sharif` specifies the group ownership of the directory. The group is set to "sharif."
  * **`user`**`: sharif` specifies the user ownership of the directory. The user is set to "sharif."

This task will create the `/home/sharif/opsshell` directory on the target server with the specified permissions, group ownership, and user ownership.

## file\_copy:

```yaml
  - name: Copy a file to remote server
    file_copy:
      src: ./script/*  # Local source file path
      dest: /home/    # Remote destination directory or if not then will be create auto.
      mode: '0755'  # File mode (e.g., '0644' for read-write permissions)
      owner: sharif  # Remote owner (username)
      group: sharif  # Remote group (groupname)
```

* **`name`**`: Copy a file to the remote server` is a user-friendly name for the task, describing what it does.
* **`file_copy`** is the Opsshell module used for copying files.
  * **`src`**`: ./script/*` specifies the local source file path. It uses a wildcard (\*) to select multiple files within the local `./script/` directory.
  * **`dest`**`: /home/` specifies the remote destination directory. In this case, it's set to `/home/`. If the directory doesn't exist on the remote server, it will be automatically created.
  * **`mode`**`: '0755'` sets the file mode (permissions) for the copied files. In this example, it's setting the file permissions to 0755, which allows read, write, and execute permissions for the owner and read and execute permissions for others.
  * **`owner`**`: sharif` specifies the owner (username) for the copied files on the remote server. In this case, the files will be owned by the user "sharif."
  * **`group`**`: sharif` specifies the group (groupname) for the copied files on the remote server. The group ownership is set to "sharif."

This task will copy the files from the local `./script/` directory to the remote `/home/` directory on the target server. It will also set the specified permissions, owner, and group for the copied files.

## git\_clone:

```yaml
  - name: Git checkout
    git_clone:
      repo: https://opsshell.example.org/path/to/repo.git
      dest: /srv/checkout
      version: master
      archive: /tmp/opsshell-examples.zip
      username: sharif
      password: sharif
```

* **`name`**`: Git checkout` is a user-friendly name for the task, describing its purpose.
* **`git_clone`** is the Opsshell module used for cloning Git repositories.
  * **`repo`**`: https://opsshell.example.org/path/to/repo.git` specifies the URL of the Git repository you want to clone. In this case, it's set to "[https://opsshell.example.org/path/to/repo.git](https://opsshell.example.org/path/to/repo.git)."
  * **`dest`**`: /srv/checkout` specifies the local destination directory where the Git repository will be cloned. It will be cloned to the "/srv/checkout" directory on the target server.
  * **`version`**`: master` specifies the branch or commit that should be checked out. In this example, it's set to "master," which is typically the default branch in Git.
  * **`archive`**`: /tmp/opsshell-examples.zip` is an optional parameter that specifies the path to an archive file that will be created with the repository contents. This is not a common use case for Git clones, and it may not be needed in most scenarios.
  * **`username`**`: sharif` and `password: sharif` are optional parameters for authentication. In this case, a username and password "sharif" are provided. However, Git repositories are usually authenticated using SSH keys or personal access tokens, and passwords are less commonly used for Git authentication.

This task will clone the specified Git repository to the `/srv/checkout` directory on the target server using the "master" branch (or another specified version).

## replace:

```yaml
  - name: Replace old hostname with new hostname 
    replace:
      path: /etc/hosts
      regexp: '(\s*)old\.host\.name'
      replace: '\1new.infolytx.name'
      
  - name: Replace old hostname with new hostname 
    replace:
      path: /etc/hosts
      after: 'sharif-VirtualBox'
      before: '# The following lines'
      regexp: '(\s*)old\.host\.name'
      replace: '\1new.infolytx.name'
```

* `name: Replace old hostname with new hostname` is a user-friendly name for the task, describing what it does.
* **`replace`**`:` is the Opsshell module used for performing text replacement within files.
  * **`path`**`: /etc/hosts` specifies the path to the file where the replacement will occur. In this case, it's the `/etc/hosts` file.
  * **`after`**`: 'sharif-VirtualBox'` defines the line after which the replacement should take place. The replacement will start on the line containing 'sharif-VirtualBox'.
  * **`before`**`: '# The following lines'` defines the line before which the replacement should take place. The replacement will stop before the line containing '# The following lines'.
  * **`regexp`**`: '(\s*)old\.host\.name'` is a regular expression used to search for the old hostname. It matches lines that contain 'old.host.name' with optional leading whitespace (e.g., tabs or spaces). The parentheses capture the leading whitespace for use in the replacement.
  * **`replace`**`: '\1new.opsshell.name'` specifies the replacement pattern. It replaces the matched regular expression with 'new.opsshell.name' while preserving the captured leading whitespace. The `\1` in the replacement string refers to the first capture group (whitespace) in the regular expression.

This task is designed to replace occurrences of 'old.host.name' with 'new.opsshell.name' in the `/etc/hosts` file, but it only does so in the section of the file that falls between the lines containing 'sharif-VirtualBox' and '# The following lines.'

## service:

```yaml
  - name: Restart vsftpd
    service:
      service_name: vsftpd
      action: restart 
```

* **`name`**`: Restart vsftpd` is a user-friendly name for the task, describing its purpose.
* **`service`** is the Opsshell module used for managing services.
  * **`service_name`**`: vsftpd` specifies the name of the service you want to manage. In this case, it's "vsftpd."
  * available : **start, stop, restart, enable, disable.**
  * **`action`**`: restart` specifies the action you want to perform on the service, which is to "restart" it. This means that the vsftpd service will be stopped and then started again, effectively restarting it.

This task will restart the vsftpd service on the target server.

## command:

```yaml
    - name: Set environment variables
      command: |
        echo 'export VAR1=value1' >> ~/.bashrc
        echo 'export VAR2=value2' >> ~/.bashrc
        source ~/.bashrc
        
    - name: just hello
      command: echo hi
```

**Task 1: Set environment variables**

* **`name`**`: Set environment variables` is a user-friendly name for the task, describing its purpose.
  * **`command`**`:` is used to specify the command(s) that should be executed on the remote server.
* The commands in this task use the `echo` command to append environment variable definitions to the `~/.bashrc` file, and then it uses `source` to load the changes.

**Task 2: Just hello**

* **`name`**`: just hello` is another user-friendly name for this task.
  * **`command`**`:` is used to run the `echo` command with the argument "hi," which simply outputs "hi."

## shell\_script:

```yaml
  - name: Run custom shell script on remote server
    shell_script:
      script: |
        #!/bin/bash
        echo "This is a custom shell script running on the remote server."
        # Add your shell script commands here

  - name: Run shell script files from a directory
    shell_files:
      directory_path: ./script/
      files:
        - script1.sh
        - script2.sh
```

**Task 1: Run a custom shell script on the remote server**

* **`name`**`: Run custom shell script on remote server` is a user-friendly name for the task, describing its purpose.
* **`shell_script`** is a custom module used for running a shell script on the remote server.
  * **`script`**`:` contains the shell script that should be executed. The script is defined using the `|` character, allowing for a multi-line script to be included.

**Task 2: Run shell script files from a directory**

* **`name`**`: Run shell script files from a directory` is another user-friendly name for this task.
* **`shell_files`** is a custom module used for running shell scripts from a specified directory on the remote server.
  * **`directory_path`**`:` specifies the path to the directory containing the shell script files you want to run.
  * **`files`**`:` is a list of shell script filenames that should be executed from the specified directory.

These tasks will execute shell scripts on the target remote server. In the case of Task 2, multiple shell scripts can be executed from a specified directory.

## apt:

```yaml
    - name: install some pakages
      apt:
        pkg:
          - dovecot-core
          - git
          - vim
        state: latest
        update_cache: true
        autoremove: true
        autoclean: true
        upgrade_dist: true
        upgrade: true
```

* **`name`**`: install some packages` is a user-friendly name for the task, describing its purpose.
* **`apt:`** is the Opsshell module used for managing packages on Debian or Ubuntu-based systems.
  * **`pkg`**`:` is a list of packages to be installed. In this case, it's specifying three packages: `dovecot-core`, `git`, and `vim`. You can add or remove packages as needed.
  * **`state`**`: latest` specifies that Opsshell should ensure that the listed packages are at their latest available versions.
  * **`update_cache:`**` ``true` triggers an update of the package cache before installing packages. This ensures that Opsshell uses the most up-to-date package information.
  * **`autoremove`**`: true` removes packages that are no longer required by any other packages on the system.
  * **`autoclean`**`: true` removes old package files from the package cache.
  * **`upgrade_dist`**`: true` performs a full upgrade of the distribution, including any pending updates and package upgrades.
  * **`upgrade`**`: true` upgrades all packages on the system to the latest versions.

This task will install or upgrade the specified packages (`dovecot-core`, `git`, and `vim`) on the target server. It will also update the package cache and perform various maintenance tasks to keep the system up to date.

## yum:

```yaml
  - name: Install a list of packages
    yum:
      name:
        - nginx
        - postgresql
        - postgresql-server
      state: present 
```

* **`name`** is a label for the task. It's used for documentation and doesn't impact the task execution.
* **`yum`**`:` module is used to manage packages on Red Hat-based Linux distributions like CentOS, Fedora, and Red Hat Enterprise Linux.
  * **`name`** is a parameter of the `yum` module, and it takes a list of packages you want to install. In this case, the task is set to install three packages: `nginx`, `postgresql`, and `postgresql-server`. You can add or remove packages from this list as needed.
  * **`state`** is another parameter of the `yum` module. It defines the desired state of the listed packages. In this task, it's set to `present`, which means Opsshell will ensure that the specified packages are installed. If you want to remove packages, you can change this to `absent`. If you want to ensure that the packages are up-to-date, you can use `latest`.
  * available state : **present, absent, latest**

For example, if you change `state` to `absent`, this task will uninstall the listed packages if they are currently installed on the target system. If you change it to `latest`, the task will update the packages to the latest available version.

## pip3:

```yaml
  - name: Install required Python packages
    pip3:
      name:
        - flask
      state: latest   
```

* `name`: This is a label for your task.
* `pip3`: The Opsshell module used for managing Python packages.
  * `name`: A list of Python packages you want to install or update. In this case, it's just "flask."
  * `state`: The desired state of the packages. Here, it's set to "latest," which means Opsshell will ensure that Flask is updated to the latest version available.
  * available state : present, absent, latest&#x20;

When you run this task, Opsshell will check the current version of Flask on the target system and update it to the latest version if a newer version is available. If Flask is not already installed, it will be installed.
